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Sixth Edition (June 1978) 


This is a major revision of, and obsoletes, GC21-7562-4. Miscellaneous technical changes 
and corrections have been made throughout the manual; changes to text and illustrations 
are indicated by a vertical line at the left of the change. 


This edition applies to the following system control programs and to all subsequent versions 
and modifications until otherwise indicated in new editions or technical newsletters. 
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Publications are not stocked at the address below. Requests for copies of IBM 
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This publication could contain technical inaccuracies or typographical errors. Address 


your comments about this publication to IBM Corporation, Publications, Department 245, 
Rochester, Minnesota 55901. Comments become the property of IBM. 


©Copyright International Business Machines Corporation 1972, 1975, 1977, 1978 


This manual describes the macro instructions provided by 
the IBM System/3 Model 10 Disk System Macros Feature. 
The publication is intended for persons who are program- 
ming in the Basic Assembler Language or its equivalent and 
who are familiar with the concept of macro instructions 
and system programming for the IBM System/3 Model 10 
Disk System. 


This publication describes how to use the macro instruc- 
tions provided through the Macros Feature. The following 
topics are discussed: 


e Coding macro instructions 

e Descriptions of the various macro instructions 

e OCL necessary to call the macro processor 

e Error conditions detected by the macro processor 

\ sample program shows how macro instructions are used. 


The IBM System/3 Model 8 is supported by IBM System/3 
Model 10 disk system control programming and program 
products. Although the Model 8 is not referenced in this 
manual, the facilities described in this manual for the Model 
10 are also applicable to the Model 8. It should be noted 
that not all devices and features which are available on the 
Model 10 are available on the Model 8. Therefore, Model 8 
users should be familiar with the contents of /BM System/3 
Model 8 Introduction, GC21-5114. | 


Minimum System Requirements 


The minimum system configuration and optional device sup- 
port for the Macros Feature is shown in the /BM System/3 


Models 4, 6, 8, 10, and 12 System Generation Reference Man- 


ual, GC21-5126. 


Preface 


System/3 Model 12 


The facilities described in this publication for the Model 10 
also apply to the Model 12 except where specifically noted 
throughout the manual. The following information concerns 
Model 12 macros only: 


$GETD/$PUTD . 

The Model 12 does not support multivolume or indexed 
disk files in the simulation area; thus AC (access) codes 
in these macros reflect these differences. 


$DTFD/$IOBD/$RDD/$WRTD 
The Model 12 uses 3340 disk drives. The valid param- 
eters for the DISK keyword are 5444, 5445, and 3340. 


$DTFU 
The Model 12 must specify a PIOB-address keyword with 
an address of a 23-byte printer 1OB area. 


5444/5445/3340 references 


All references to 5444 relate to the simulation area, and 
all references to 5445 relate to the main data area. 


ene 


Related Publications 


The following publications contain information which 
further describes topics discussed in this manual: 


IBM System/3 Basic Assembler Reference Manual, 
$C21-7509 


IBM System/3 Models 4, 6, 8, and 10 System Control 
Program Logic Manual, SY21-0502 


/BM System/3 Models 8 and 10 System Control 
Programming Reference Manual. GC21-7512 


IBM System/3 Model 8 Introduction, GC21-5114 


IBM System/3 Models 4, 6, 8, and 10 Data Management 
and Input/Output Supervisor Logic Manual, SY21-0512 


IBM System/3 Models 8, 10, 12, and 15 Components 
Reference Manual, GA21-9236 


IBM System/3 Model 12 Introduction, GC21-5116 


IBM System/3 Model 12 System Control Programming 
Reference Manual, GC21-5130 


IBM System/3 Model 12 System Control Program Logic 
Manual, SY21-0046 


IBM System/3 Model 12 User’s Guide, GC21-5142 


IBM System/3 Multiline/Multipoint Binary Synchronous 
Communications Reference Manual, GC21-7573 


IBM System/3 Multiple Line Terminal Adapter RPQ 
Program Reference and Component Description Manual, 
GC21-7560 | 
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Chapter 1. Introduction 


A macro instruction is a source statement that causes The operands specify available services and options. The 
generation of a predetermined set of assembler statements Operands must start in column 14 and are written as follows: 
each time the macro instruction is used. The Macros 
Feature is a macro processor that provides macro instruc- 1. Each operand consists of a keyword followed by a 

. tions which perform both system services and input/output dash and a parameter. 


device support. By using these macro instructions, you can 
perform both system and input/output operations with 
less coding. | 


Figure 1 is an overview of the operation of the macro 

processor. The OCL statements used to call the macro 2. No blanks should be left between operands. 
processor are explained in Chapter 3: OCL and Sample 
Program. 


WRITING MACRO INSTRUCTIONS 


| 3: Commas precede all but the first operand. 
You code macro instructions as follows: 


[,PACK-P/S] 


Starting 


Column 1 8 14 72 | 4 | 
@ | 4. The parameter part of the operand must immediately 


follow the dash. 


Symbol | Macro No operands Any nonblank 


or blank | name Or one or more | character if 
separated by continuation is 
commas being used 


5. |The keyword part of each operand must correspond 
to one of the keywords in the macro instruction 
The name field may contain any valid assembly language description. 
symbolic name beginning in column 1. The name its 
assigned to the first byte of generated code. Since the 
name is optional, it is shown enclosed in brackets. 


6. Some operands are not required. These optional 
operands are indicated by enclosing the operand 
within brackets [KEYWORD-parameter] . 


The desired mnemonic operation code (macro instruction 
: name) must appear as specified in the macro instruction 
description. The operation code must start in column 8. 
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Source Statements 


This is your program. 
It includes macro 
statements. 


Prius This indicates the beginning 


of the next job. 


Source 


Statements This indicates the end of your job. 


OCL 
Statements 


IBM System/3 Model 10 1OCS 
Macro Processor 


The macro processor reads source state- 
ments from either the system input 
device or a-source library. 


OCL Statements 


Load the macro processor. 
OCL can be entered through 
system input device or called 
from the procedure tibrary. 


e All valid assembler statements and 
comments are placed in $$;OURCE. 


e@ Macro statements are listed in 
$SOURCE, preceded by an 
asterisk, and followed by the 

macro expansion. 


“e@ Macro expansion statements are 
marked (by the macro processor) in 
position 96 in $SOURCE and indi- 
cated on the assembly listing by a 

. Plus sign (+) preceding the expan- 
sion statement. 


@ Invalid statements are flagged and 
placed in $SOURCE. 


$SOURCE 


$SOURCE File | | 
Statements placed in 

$SOURCE are used as 

source input to an 

assembler. 


Figure 1. Macro Processor Overview 


7. An option list for a keyword parameter is specified 
as follows: 


KEYWORD-A/B/C 


eo ees oe 9. No operands may be specified beyond column 71. 
This list indicates that the keyword has the options lf continuation is required, column 72 must contain 
A,B, or ©. These are the only valid options for the a nonblank character and the last operand must be 


keyword parameter. 


followed by a comma. An operand cannot be 
divided and continued on the next line. The operands 
of the continued field must begin in column 14. For 
an example of continuation coding, see Figure 2. 


10. Comments must be separated from the operand or 
comma by at least one blank space. Comments can- 
not be inserted between operands on a one-line macro 
instruction. Figure 3 shows examples of comments 
used with macro instructions. On the assembly 
listing, all comments on the generated code are 
justified by the macro processor to begin in column 
40. Any comments too long to be contained in 
columns 40 through 71 are truncated from the right. 


When the options Y/N are given in a macro instruc- 
tion, Y indicates a yes response, N indicates a no 
response. 


8. The operands may be written in any order. If a key- 
word is not specified, the default value is used. A 
default value is selected for optional keywords that 
are omitted. The default value is indicated in the 
macro instruction description by a line under the 
default option. For example, [KEY-A/B/C] indi- 
cates the option A is the default value. 
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Figure 3. Comments on Macro Instructions 
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MACRO INSTRUCTIONS PROVIDED 


The macro instructions provided through the macro 
processor and the functions they perform are shown in 
Figure 4. 


All code for the macro instructions must be on the program 
pack or the system packs The program pack is the disk pack 
from which the macro processor is loaded. The system pack 
is the disk pack from which initial program load (IPL) is 
performed. 


You may want to delete some macro instructions from 
your library to reduce the amount of disk space required 
for the macro instructions. For instance, if vour system 
does not include the 3410/3411 Magnetic Tape Subsystem, 
the tape macro instructions would be of no use to you, and 
you might wish to delete them to save space. You can 
delete macro instructions from your library by using the 
library maintenance utility program, $MAINT. 


System 
Services 


General 
1/O 
Support 


Unit 
Record 
Device 
Support 


Disk 
Device 
Support 


Tape 
Device 
Support 


3741 
Device 
Support 


Macro 


Instruction 


Name 


$COMN 
$EOJ 
$FIND 
SFTCH 
$LOAD 
$SNAP 
$SVC 
S$TRAN 


$TRL 
$TRTB 


$XCTL 


$ALOC 
$CHK 
$CKL 
$CLOS 
SOPEN 


$DTFU 
$DTOU 
$GPU 

$PKBU 


$PRNT 


$DTFD - 
$DTOD 
$GETD 
$10BD 
$IOED 
$PUTD 
$RDD 
S$WAIT 
$WRTD 


$CTLT 
$DTFT 
$DTOT 
$GETT 
$PUTT 
$RDT 

S$WRTT 
SWTT 


$DTFK 
$DTOD 
$GETK 
S$PUTK 


$CCP 
$LCP 
$SCP 


Descriptive Name 


Common Equates 

End of job 

Find a directory entry 

Load a module and pass control 
Load a module 

Snap dump main storage 
Supervisor call 


Generate an interface to the translate 


routine 


Generate a translate parameter list 


Generate a translate table 


Load a module and exchange control 


Allocate space 

Check for 1/O completion 
Generate a check list 

Prepare a device for termination 
Prepare an I/O device 


Define the file for unit record yoy © 0.4" 


Unit record DTF offsets 
GET or PUT for unit record 


Construct an interface to the printer- 


keyboard 
Print a message 


Define the file for disk 

Disk DTF offsets 

Construct a disk GET interface 
Input/output block for disk 
input/output block offsets 
Construct a disk PUT interface 
Read from disk 

Wait for disk 1OS completion 
Write to disk 


Control command for tape 
Define the file for tape 

Tape DTF offsets 

Construct a tape GET interface 
Construct a tape PUT interface 
Read from tape 

Write to tape 

Wait for tape 1/O completion 


Define the file for 3741 

3741 DTF offsets 

Construct a 3741 GET interface 
Construct a 3741 PUT interface 


Command CPU 
Load CPU 
Store CPU 


Figure 4. Macro Instructions 


You code macro instructions to generate a block of assem- 
bler statements to perform a certain function. Some func- 
tions may be the same each time they are used, others may 
be modified by specifying different operands. This chapter 
explains the System/3 macro instructions in detail. 


The macro instructions are grouped in this chapter accord- 
ing to the functions they perform: 


@e Common equates 

e@ System services 

e | Input/output support 

Input/output support macro instructions are further 
divided according to the device supported. 

Common Equates ($COMN) 


This macro instruction provides equates for various labels 
and values used by other macro instructions. 


The format of the $COMN macro instruction is: 


Chapter 2. Macro Instruction Statements 


Programming Considerations 


When you use the macro processor you should remember 
the following restrictions. First, the generated code for 
some macro instructions uses register 1, and the generated 
code for other macro instructions uses register 2. You 
should save the contents of the register used by the 
generated code before issuing the macro instruction. Other- 
wise, the contents are destroyed. These macro instructions 
use register 1: 


$RDD 
$STRAN 
$WRTD 
SWAIT 


These macro instructions use register 2: 


| | $COMN | | | 


You must generate equates using $COMN whenever any of 
the following macro instructions are used in your program: 


$ALOC $PRNT 
$CLOS $PUTD 
$CTLT $PUTK 
$FIND $PUTT 
$FTCH $RDD 
$GETD $RDT 
$GETK $WRTD 
$GETT SWRTT 
$GPU SWAIT 
$LOAD SWTT 
SOPEN $XCTL 
$PKBU 


$ALOC SOPEN 
$CHK $PKBU 
$CLOS $PRNT 
$CTLT $PUTK 
$FIND $PUTT 
$FTCH $PUTD 
$GETD $RDT 
$GETK SWRTT 
$SGETT SWTT 
$GPU $XCTL 
$LOAD 


The second consideration concerns the labels you use in 
your program. System routines and some generated code 
have labels beginning with the dollar sign ($). To avoid 
duplicate label errors, you should not use the dollar sign 
as the first character of labels in programs using the macro 
processor. 
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SYSTEM SERVICES 

By using system services macro instructions, you can com- 
municate with the System/3 system control program. 
These macro instructions can do the following: 

@ Read records from the system input device. 


e@ Log and write error messages. 


@ Pass control to an inquiry program and receive control: 
after the inquiry program has finished. 


e@ Determine the location of an object module on disk. 


e@ Obtain object modules from disk and load them into | 
main storage. 


@ Pass control to modules in main storage. 
e@ Build and use a translate list. 


e Dump a part of main storage during execution of your 
program. | 


@ Terminate the current job. 


Supervisor Call ($SVC) 


The supervisor call macro instruction branches to one of 
the following system routines: 


@ System input (SYSIN) 

@ Halt/syslog 

e VTOC read 

e@ Rollout/rollin 

A detailed description of each of these routines is contained 


in the /BM System/3 Models 4, 6, 8, and 10 System Control 
Program Logic Manual, SY21-0502. 


The format of the $SVC macro instruction is: 

[Name] $SVC RIB-SYSIN/HALT/VTOC/ROLL 
RIB-SYSIN, HALT, VTOC, or ROLL indicates the system 
routine you want to call. The following discussion explains 


how you can use these routines through the macro instruc- 
tion. 


System Input (SYSIN) 


You read a record from the system input device by calling | @ 
the system input routine through the $SVC macro instruc- ; 

tion. The system input device may be any one of the 

following: 


@ 5471 printer keyboard. Only 96-byte, single-buffered 
input is allowed for this device. Double buffering is 
ignored. 


@ 1442 card reader. Single and double buffering are sup- 


ported. Only 80 bytes of the 96-byte buffer are used as 

input; the remaining 16 bytes are cleared to blanks. If . 
single buffering is not indicated, double buffering is 

assumed. 


@ 5424 multi-function card unit (MFCU). Both single and 
double buffering are supported. Support for both the 
primary (MFCU1) and secondary (MFCU2) hoppers is 
provided. All 96 bytes are used as input. If single buf- 
fering is not specified, double buffering is assumed. 


@ 3741 Data Station/Programmable Work Station, directly 
attached. Both single and double buffering are supported. 
If single buffering is not specified, double buffering is 
assumed. Only 96-byte records are supported. 


To call the system input routine, you must do the following: @ 


1. Construct a parameter list as input to the system 
input routine. For the required parameter list, see 
Part 6 of /BM System/3 Models 4, 6, 8, and 10 
System Control Program Logic Manual, SY21-0502. 


2. Put the address of the parameter list in register 2. 


3. Issue the macro instruction: 
[Name] $SVC RIB-SYSIN 


4. Analyze the return code provided by system input. . 


The macro processor generates the coding required to 

branch to the system input routine. The system input ~ 
routine reads the input record and returns control to your 

program with a return code in the first byte of the param- 

eter list. Because of this, you must reset the operation 

code before each call to system input. You must analyze 

the return code to determine the outcome of the operation. 


Halt/Syslog 


Specifying RIB-HALT in your $SVC macro instruction 
calls halt/syslog: a group of system output routines pro- 
viding communication with the operator. You may want | 
to use halt/syslog to notify the operator of error conditions, 
error recovery procedures, and the validity of previous 
operator responses to halts. If the operator selects an in- 
valid option in response to a halt, the response is not accep- 
ted by halt/syslog. Instead, another halt is issued to the 
operator until a correct option is taken. When an immedi- 
ate cancel (option 3) is selected, control is passed directly 
to the end-of-job (EOJ) routine by halt/syslog. 


Two types of printed output are available thraugh halt/ 
syslog. Both are printed on the system log device. 


e A log is a 4 or 6-character statement which identifies 
the type and source of an error. 


@ A message is a printed statement which may be used to 
indicate errors that have occurred or to issue instructions 
to the operator, such as requesting that a disk file be 
placed on a Certain drive. 


Both logs and messages may be issued with or without an 
accompanying halt. 


Note: You cannot issue system halts through the $SVC 
macro instruction, but you may design your halts to indi- 
cate the same errors and accept the same responses as the 
system halts. 

Three devices may be used as the system log device: 

@ 5203 line printer (left carriage only) 

@ 1403 line printer 

@ 5471 printer-keyboard 

The device used is determined when you perform initial 


program load (IPL). You may change devices by entering 
a // LOG statement in your job stream. 


To use halt/syslog you must do the following: 


fi: Build the appropriate parameter list as determined by 


the function you want to perform. The parameter 
list formats are described in Appendix B of /BM 
System/3 Models 4, 6, 8, and 10 System Control 
Program Logic Manual, SY21-0502. 


2. Put the address of the parameter list in register 2. 


3. Issue the macro instruction: 


[Name] $SVC RIB-HALT 


4. Process the operator’s reply in your program. 


The generated code passes control to the halt/syslog 
routine. The halt/syslog routine performs the operation 
indicated by the parameter list. If a reply is to be returned 
by the operator, halt/syslog ensures that the reply is valid 
and returns it to your program in the parameter list. You 
must then process the reply. If the operator’s reply is not 
valid, a halt is issued until a valid reply is given. 


Note: When option 3 (immediate cancel) is selected by 
the operator, control is passed from halt/syslog directly 

to the end-of-job (EOJ) routine. 

VTOC Read 

You can perform input operations on various data areas 
on cylinder zero of disk files on the IBM 5444 Disk Storage 
Drive by using the volume table of contents (VTOC) read | 
routine. This routine cannot be used for files on the IBM 
5445 Disk Storage Drive. 

The data areas you have access to are: 

@ Volume label 

@ Volume table of contents (VTOC) index 

@ Format-1 labels 


e Configuration records 


You call the VTOC read routine by specifying RIB-VTOC 
in the $SVC macro instruction. 
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Volume Label is one sector (256 bytes) containing the 
volume identification, VTOC location, and a system 
directory that shows the status and location of the source 
and object libraries. Volume label requests allow you to 
read information from the volume label. The format of 
the volume label is given in Figure 5. 


VTOC Index consists of two sectors (512 bytes) contain- 
ing one 10-byte entry for each file in the volume. Each 
10-byte entry contains the name of the referenced file and 
the location of the format-1 label associated with the file. 
Figure 6 shows the format of the VTOC index. 


Format-1 Label describes each file maintained on the disk 
pack. The format-1 request allows you to read a format-1 
label. Figure 7 describes the format-1 label. Each label is 
64 bytes long. 


Configuration Record is one sector (256 bytes) providing 
device information to the system. The configuration record 
format is provided in Appendix A of /BM System/3 Models 
4,6, 8, and 10 System Control Program Logic Manual, 
SY21-0502. 


Calling VTOC Read requires the following steps: 


1. Build the parameter list describing the operation to 
be performed. The parameter list is described in Part 
6 of /BM System/3 Models 4, 6, 8, and 10 System 
Control Program Logic Manual, SY21-0502. 


2. Put the address of the parameter list in register 2. 


3: Issue the macro instruction: 


[Name] $SVC RIB-VTOC 


4. Check the return code to determine the outcome of 
the operation. 


When you issue the $SVC macro instruction specifying 
RIB-VTOC, the generated code calls the VTOC read 
routine. VTOC read performs the operation and returns 
control to you with the address of the parameter list still 
in register 2. 


Rollout 


You use rollout to interrupt the current program so that 


another program can be executed. When the second pro- 
gram is finished, the first program is reinstated and con- 
tinues executing. A program that calls rollout is rolled out 
and when the interrupting program is completed, the first 
program is rolled in. 


The 5471 printer keyboard is required for a rollout request. 
Once rollout is initiated, the printer keyboard becomes the 
system input device. 


When using rollout, you should follow these procedures: 


1. Be certain the following restrictions are met: 


@ A program calling rollout cannot run in program 
level 2. 


@ A rollout-calling program must be so defined to the 
linkage editor. 


@ Programs cannot run in program level 2 when 
rollout-calling program is in program level 1. 


@ The same I/O devices are available to the interrupting 
program as were available to the original program. 


@ Whenever an interrupting program shares the same 
disk files as a rolled-out program, only reading and 
updating are allowed by the two programs. Loading 
and additions are not allowed. 


2: Determine whether rollout has been requested by 


testing the inquiry-request-pending bit in the system 
communication region. If the request is pending, call 
rollout. If it is not on, proceed with the current 
program. 


3. Set on the rollout request bit in the system com- 
munication region. | 


4. Issue the macro instruction: 


[Name] $SVC RIB-ROLL 
5. Set off the rollout request bit in the system com- 
munication region. 


The coding generated by the $SVC macro instruction calls 
the rollout routine. Rollout performs the following steps: 


1. Places the current program (program being executed) 
and the current contents of the scheduler work area 
on disk. 


2. Allows a new program to be loaded in place of the 
current program and passes control to the new 
program. 


3. Reloads the original program and previous contents 
of the scheduler work area and passes control to the 
point where the original program was interrupted. 


Contents of Volume Label 


3 VOL (Label identifier) 
6 Volume identifier, 1-6 characters 
2 VTOC index pointer (C/S) 


System Directory 
Source Library 
Source directory pointer 
Next available library sector 
End of library 
Number of directory sectors 
Number of permanent library sectors 
Number of active library sectors 
Number of available library sectors 
Reserved 
Object Library 
Object directory pointer 
End of directory 
Start of library 
Allocated end of library 
Extended end of library 
Number of available permanent directory entries 
Number of available temporary directory entries 
First temporary directory entry (C/S/D) 
Next available temporarv directory entry (C/S/D) 
Next available library sector for permanent library entries 
Next available library sector for temporary library entries 
Number of available library sectors for permanent library entries (after last PERM) 
Number of available library sectors for temporary library entries 
Total number of active library sectors 
Number of active O type permanent sectors 
Number of active R type permanent sectors 
System Information | 
1 System indicator 
2 Rollin/Rollout pointer 
1. Rollin/Rollout size (tracks) 
2 SWA pointer 
1 
4 


NNNMNNMDNN 


wad 


NONNNNND WWHNNNN ND NO 


SWA size (tracks) 
Start and end of library (C/S) 


10 Owner ID 
14 Device constants 
12 Alternate track assignments 
51 Available tracks (Format-5) 
11 Save area for copypack, $COPY utility 
1 Run OXRE indicator 
1 Reserved 
3 Reserved 
2 Checkpoint/Restart 
15 Unused 
4 Reserved 
10 Scientific system file indicator 
24 Suspected defective track indicators 
16 Reserved 


. References in this table to C/S indicate the cylinder and sector location of the field. Cylinder and sector 
are given in hex numbers. References to C/S/D indicate the cylinder, sector, and displacement into the 
sector of the field. Again, all are given in hex numbers. 

2. Fields in the volume label that tell the number or quantity of various entries on the disk are hex numbers. 


Figure 5. Volume Label Format 
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Number 


of Bytes | Contents 


Not used 


Index with up to 50 entries of the 


following format: 


8 bytes—Filename left-justified (20 


Al 8 |e jeje lr 


indicates duplicate name in the index 


2 bytes—Sector number and displace- 
“ment within that sector or file entry 


the S list 


the S list 


index (Only P and T formats are 
considered not free.) 


Figure 6. Volume Table of Contents (VTOC) Index Format 


Number 


of Bytes Description 


Entry ID 
Chain address 
Filename 
Date 
Retain 
File type 


Record length 
Key length 

Key location 
Last record 

Last key 

Data start 

Data end 

Index start 

Index end 
Records or tracks 


™ NONNMN WOON — NO 


Number of records or tracks 
Volume sequence number 
Back pointer 


= 
On—N 


Number of Format-1's on the S list 


S/D address of the last member on 


Number of free entries in the VTOC 


Note: The remaining 6 bytes are as follows: 


S/D address of the first member on 


Entry identification pointer to VT OC index 
Sector number or displacement into sector of next Format-1 
Filename 


Date of file 
Retain indicator for file (P, S, or T) 
Byte Value Meaning 
1 X‘00’ Should be zero 
2 X‘80’ Indexed file 
X’40’ Consecutive file 
X‘20’ Direct file 
X‘10' Multivolume file 
X’08’ Last pack of a consecutive MVF only 


The number of bytes within each record 
The number of bytes within the record key 
Sector number/displacement into the sector 
Last record displacement (C/S/D) 

Last key displacement (C/S/D) 

Start of data address (C/S) 

End of data address (C/S) 

Start of index address (C/S) 

End of index address (C/S) 

X‘80’—number of tracks 

X’00’—number of records 

Number of record/tracks created (see previous byte) 
Volume sequence number for MVF 

Back pointer for scratch files 

Not returned by VTOC read 


Note: Contents in this table given as C/S indicate a two-byte address given as cylinder number/sector number. 
C/S/D indicates a three-byte address giving cylinder number/sector number/displacement. The numbers are hex. 


Figure 7. Format-1 Label Format 
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Find a Directory Entry ($F IND) 


A load module must be in the object library. Specific 
information must be obtained from the module’s object 
library directory entry before a load or fetch can be per- 
formed. There are two ways you can locate a load module 
and obtain the information: 


@ Issue a $FIND before issuing a $LOAD, Form Il. The 
information obtained during the find is used during 
the load operation. 


e Issue a load with find (SLOAD, Form |), a fetch 
($F TCH) or a fetch to address (SXCTL). These func- 
tions perform the find operation as part of their normal 
functions. 


The $FIND macro instruction searches the object library 
directory for the requested module name and returns the 
directory entry in the parameter list. If you will need to 
use the data in register 2 at a later time, you should save 
the contents of that register before issuing the $F IND 
macro instruction. 


The format of the $FIND macro instruction is: 


[Name] $FIND NAME-module[,FIND-address] 
| [,PACK-P/S] 


NAME-module provides the name of the module to be 


found. Only names of object modules (O modules) can be 


entered here. 


FIND-address specifies the label that becomes the address 
of a 12-byte parameter list built by the generated code. 


Initially the parameter list contains input to the supervisor. 


After execution, it contains the directory entry of the 
module. The format and contents of the parameter list 
after execution are shown in Figure 8. If this operand is 
not specified, a macro label is generated. 


PACK-P or S specifies the program disk pack (P) or the 
system disk pack (S) to be searched. If this operand is not 
specified, P is assumed. 


Load a Module (S$LOAD) 


This macro instruction loads a module into storage at the 
address you specify. Control is returned after the module 
has been loaded. You may then pass control to the 
module at the specified address. If you will need to use 
the data in register 2 at a later time, you should save the 
contents of that register before issuing the $LOAD macro 
instruction. Two forms of this macro can be used. 


Load with Find (Form !) 


The load with find macro instruction locates the module 
and loads it into main storage. 


The format of this macro instruction ts: 


NAME-module name[,FIND-address] 
[,LOAD-2/address] [,USE-R/NR] 
[,PLIST-address] [,PACK-P/S] 


NAME-module name provides the name of the module to 
be loaded and is required. Only O modules can be specified. 


FIND-address becomes the address of the parameter list 
passed to the find routine. The parameter list is generated 
by the macro processor. After execution of the load, this 
parameter list contains the modified entry for the module 
as shown in Figure 9. | 


LOAD-2 or address specifies the address where the module 
is to be loaded into main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 


USE-R or NR indicates whether the code generated by the 
macro instruction is to be reusable (R) or nonreusable (NR). 
If the operand is not specified, NR is assumed. 


You can reuse the generated code to load the same module 
more than one time, or to load different modules. If you 
wish to load different modules using the same generated 


code, you should also specify the PLIST operand. 
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Number Displace- 


Entry of Bytes 


Disk Address 


No. of Text 
Sectors 


Link Edit 
Address 


Disp. of RLDs 


Entry Point 
Address 


Storage Size 


Attributes 


Cylinder/sector address of the module. 


Text sector length of the module in hexadecimal 


Hexadecimal storage address at which the module was linkage edited. 


Number of bytes, in hexadecimal, into the first sector containing RLDs, 
of the first relocation directory (RLD) entry of the module. 


Hexadecimal storage address at which program execution begins (with- 


out RLDs). 


Amount of storage (in sectors) required to execute the program. 


Byte 1: 
Bit O 


“Qo WN = 


Byte 2: 


Oo 


1 = Permanent entry 

O = Temporary entry 

1 = Inquiry program 

1 = Rollout-calling program 

1 = Must run in dedicated environment 
1 = Requires source information 

1 = Deferred mounting allowed 

1= PTF applied 

1 = Overlay object program 


1 = The system input device must be dedicated to this program 
1 = Checkpoint/Restart program 
1 = This program will access the source file directly 
1 = Macro processor is allowed 
Reserved 
1 = This program requires that a new load address 
be calculated at load time to place it in main 
storage beyond its own program common region 
Reserved 
Reserved 


Release version of this entry. 


Note: Determination of displacement into the parameter list begins with 0. 


Figure 8. Find Parameter List Description 


Number Displace- 
of Bytes | ment 
Disk Address 


No. of Text 
Sectors 


Link Edited 
Address 


Disp. of RLDs 


Relocated Entry 
Point Address 


Load Address 


Description 


Cylinder/sector address of the module in hexadecimal. See note. 


Text sector length of the module, in hexadecimal. 


Storage address at which the module was linkage edited. 


Hexadecimal displacement, in bytes, into the first sector containing RLDs, 


of the first relocation directory (RLD) entry of the module. 


Storage address at which program execution begins, after resolving RLDs. 


Address at which the requested module is loaded. 


Note: \f a directory entry was not found on a load with find, the first byte contains a character O. 
Determination of displacement into the parameter list begins with 0. 


Figure 9. Find Parameter List after Load Execution 


PLIST-address is used only when the generated code is 
reusable. The address specified identifies the leftmost 
byte of a parameter list passed to the load routine. To 
load a different module using the same generated code, 
you must update the parameter list to indicate the desired 
module. Figure 10 shows the format and contents of the 
parameter list. 


PACK-P or S specifies the program disk pack (P) or the 
system disk pack (S) containing the requested module. 


Load Only (Form [1) 


The load-only macro instruction loads a module previously 
found by the $FIND macro instruction. The format of 
this macro instruction is: 7 


FIND-address[,LOAD-2/address] 
[,PACK-P/S] 


FIND-address is the address used in the previous $F IND 
macro instruction. It identifies the directory entry of the 
module in main storage. After execution of the load, this 
address points to the directory entry of the module as 
shown in Figure 9. 


LOAD-2 or address specifies the address where the module 
is to be loaded in main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 


PACK-P or S specifies the program disk pack (P) or system 
disk pack (S) containing the requested module. 


Number Displace- 
of Bytes ment 
Module Type 
Module Name 
FE 


Load Address 


Figure 10. ‘Load Parameter List Description 


Load a Module and Pass Control ($F TCH) 


The fetch macro instruction ($F TCH) finds a module in 
the directory, loads the module into main storage, and 
passes control to it. Your program does not regain control. — 
When a module is fetched into main storage, the relocation 
factor is added, as necessary, to the module’s link edit 
address. This determines the location in main storage 
where the module is loaded. The module receives control 
at its entry point. 


The format of the $F TCH macro instruction is: 


| [Name] | $FTCH | NAME-module name[,PACK-P/S] | 


NAME-module name specifies the object module to be 
fetched into main storage. The name must be the same as 
the name in the directory entry. 


PACK-P or S specifies the program disk pack (P) or the 
system disk pack (S) containing the requested module. 


Description 


Must contain O to indicate an object module. 
The name of the module to be loaded. 


X'FE’ 


The address at which the module is to be loaded. 
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Load a Module and Exchange Control ($XCTL) 


This macro instruction finds a module in the directory, 
loads the module into main storage at the address you 
specify, and passes control to it. Control is not returned 
to your program. As with the $F TCH macro instruction, 
relocation factors are resolved, and control is passed to 
the entry point of the program. 


The format of the $XCTL macro instruction is: 


NAME-module name[,LOAD-2/address] 


[,PACK-P/S] 


NAME-module name specifies the name of the module to 
be loaded and given control. The module must be an O 
module. | 


LOAD-2 or address specifies the address where the module 
is to be loaded in main storage. The 2 indicates that the — 
address is in register 2; the address is the symbolic address 

_where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 


PACK-P or S specifies the program disk pack (P) or the 
system disk pack (S) containing the requested module. 
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Generate a Translate Parameter List (STRL) 


This macro instruction generates a parameter list needed 
by the Model 10 Translate routine. This list is called via 
the $TRAN macro instruction. $TRL does not generate 
executable code. Figure 11 shows the format of the 
translate parameter list. 


Translate Routine Operation 


To use the Model 10 translate routine, you must provide a 
translate area. The format of the area is: 


Byte Field Description 


0 Byte contents used to determine whether a 
character is to be translated. 


1 Byte contents are substituted for characters 
that are not to be translated. 


2-257 256-byte translate table. 


The translate routine processes a field, specified by the 
$TRAN macro instruction, one byte at a time. 


The translate table must be constructed so that the displace- 
ment (from the beginning of the table) of the translated 
representation of a character is equal to the hexadecimal 
representation of the untranslated character. 


Note: \f you are using the IBM System/3 Model 10 Disk 
System Multiple Line Terminal Adapter Input/Output 
Control System, Program Number 5799-WAU, the translate 
area is provided. 


The contents of the byte at a given displacement are com- 
pared with the contents of the first byte in the translate 
area (byte 0). If an equal compare results, the character is 
considered to be invalid and the following actions are 
performed: 


@e The completion code in the parameter list is set to indi- 
cate that an invalid character was detected. 


@ The hexadecimal value in the second byte of the trans- 
late area (byte 1) is substituted for the original 
character. 


If an unequal compare results, the hexadecimal value in the 
translate table is substituted for the original character. 


The format of the $TRL macro instruction is: 


TO-address,-F ROM-address, 
LEN-number,TRT-address 


[Name] $TRL 


TO-address specifies the symbolic address of the first byte 
of the data to which the translated data will be moved. 


FROM-adaress specifies the symbolic address of the first 


byte of the data field to be translated. This address may 
be the same as the address specified in the TO operand. 


LEN-number specifies the decimal length of the FROM 
field. 


TRT-address specifies the symbolic address of the first byte 
of the translate area. 


All four operands are required. 


Generate a Translate Table (STRTB) 


This macro instruction generates an EBCDIC to ASCII or 
an ASCH to EBCDIC translate table. The table is generated 
in the format required by the $TRL macro instruction, and 
can be addressed by $TRL when you translate data. 


The format of the $TRTB macro instruction is: 
[Name] 


$TRTB [CODE-E/A] [,HEX-hex] — 


name specifies the symbolic address of the first byte of 


the generated translate table. 


CODE-E/A specifies whether the character code of the 
data to be translated is EBCDIC (E) or ASCII (A). If this 
operand is omitted, EBCDIC (E) is assumed. If CODE-E 
is specified, $TRTB generates a 258-byte table; if CODE-A 
is specified, $TRTB generates a 130-byte table. 


Note: \f you specify CODE-A, you may want to specify 


DC 128XL1’FF’ after the $TRTB macro instruction to 
allow for invalid ASCII characters. 


HEX-hex specifies the hexadecimal pattern with which to 
replace any invalid characters found during translation. If 
the HEX operand is not specified, the replacement char- 
acter is a blank. 
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Generate an Interface to the Translate Routine (STRAN) Snap Dump Main Storage ($SNAP) @ 


This macro instruction generates an interface to the Model This macro instruction provides an interface with the non- 
10 translate routine. After the translate routine has finished, - terminating system storage dump routine. You must specify 
control is returned to your program with a completion code a dump identifier and the limits of the area to be dumped. 
in the translate routine parameter list. The address of the The contents of the specified main storage area are put on 
para... “> list is in register 1. You should check the com- the system logging device; therefore, it is recommended 
pletion code to ses ‘f any characters that are not to be that the logging device be a printer. Output from the dump 
translated were encountered. routine consists of: 

The format of the $TRAN macro instruction is: - @ The specified dump identifier 


e Thecontents of registers 1 and 2 


N TRAN TRL-add st ; 
[Name] $ [ address] e@ The contents of the specified main storage area . 


Control is returned to the next sequential instruction in 
TRL-address specifies the symbolic address of the translate your program. 


parameter list. If this operand is not entered, the address 


is assumed to be in register 1. See Figure 11 for a descrip- 
tion of the parameter list. | The format of the $SNAP macro instruction is: 


; : [Name] $SNAP 1D-hex,START -address,END-address 
ene Field Description 
Length P 
Address of the translate area (your program must 
define the translate area) /D-hex specifies a 2-byte hexadecimal number to be used © 
FROM field address, for translation as the dump identifier 


TO field address for translation 


START-address specifies the symbolic address of the low- 


Number of bytes to translate storage limit of the area to be dumped. 


Completion code: 
X‘00’—translation complete, no errors 
X‘FF‘—invalid character detected 


END-address specifies the symbolic address of the high- 
storage limit of the area to be dumped. 


All three operands are required. 


Figure 11. Translate Parameter List 


End-of-Job ($EOJ) 
The $EOJ macro instruction passes control to the end-of- 
job routine. This routine returns control to the supervisor 


for normal end-of-job. 


The format of the macro instruction is: 


| [Name] | $EOJ | | 
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INPUT/OUTPUT SUPPORT General I/O Support 


The input/output support macro instructions provide The general 1/O support macro instructions are used with 
access to devices without requiring you to write extensive both unit record and disk devices. The normal sequence 
routines to perform each function. The input/output sup- for using these macro instructions is: 


port macro instructions are divided into four groups: 
| 1. | $ALOC to allocate the disk file or the unit record 
e General—macro instructions used with all device types. device to your program level. 
The following macros are in this group: 
2. SOPEN to prepare the disk file or unit record device 


$ALOC for use. 

SOPEN | | 

$CKL  ( 5471 Console and 3: 1/O operations and any processing required. 
$SCHK f Teleprocessing only 

$CLOS | 4. $CLOS to prepare the disk file and/or unit record 


device for job termination. 
@ Unit Record—macro instructions that support unit- 


record devices. The following macros are in this group: 


$DTFU_ 
$DTOU 
$GPU 
$PKBU 
$PRNT 


e Disk—macro instructions that support disk devices. The 
following macros are in this group: 


$DTFD $RDD 
$DTOD $PUTD 
$1OBD $WRTD 
$IOED SWAIT 
$GETD 


@ Tape—macro instructions that support tape devices. The 
following macros are in this group: 


$DTFT $PUTT 
$DTOT SWRTT 
$GETT $CTLT 
$RDT SWTT 


@ 3741—macro instructions that support the 3741. The 
following macros are in this group: 


$DTFK 


$GETK 
SPUTK 
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Allocate Space (SA LOC) 


The routines called by the $ALOC macro instruction 
allocate input/output devices and space on disk devices. 
These routines check to ensure that: 


e The system supports the requested device. 


@ The device requested is available to the requesting 
program. 


e The DTF tables do not extend into the last 1K (1024) 
bytes of the calling program. 


e@ The LOCATION parameter of the OCL FILE statement is- 


valid. 


@ The correct disk pack is mounted and space is available 
to the calling program. 


e No more than 40 DTFs (disk and tape) are present in 
the calling program. 


e The correct tape input file is mounted, or the tape label 
is written on the output file, and that the tape is posi- 
tioned at the beginning of the file. 


An allocate request requires that pre-open DTFs be sup- 
plied as input to the routine. For a description of DTFs, 

see Define the File for Unit Record (SDTFU), Define the 
File for Disk (SDTFD), Define the File for 3741 (SDTFK), 
and Define the File for Tape (SDTFT). When the allocate 
request is for a disk or tape device, OCL file statements are 
also required. More than one DTF can be allocated at one 
time by chaining the DTFs. To chain DTFs, you must enter 
the address of the next DTF in the DTF you are building. 
The last DTF in a chain has X’FFFF’ entered in place of the 
address. If your program operates as an interrupt handler, 
such as a Binary Synchronous Communications program or 
a Multiple Line Terminal Adapter program, all DTFs in the 
program should be chained together and allocated on one 
operation. When an error condition occurs, the allocate 
routine calls halt/syslog to display the proper halt code. 


Note that if you will need to use the data in register 2 at a 


later time, you should save the contents of that register 
before issuing the $A4LOC macro instruction. 
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The following output is produced when control is returned 
to your program. 


e@ The contents of register 1 are restored. 

e The format-1 labels and configuration record are updated. 

e For a non-disk or non-tape DTF, bit 1 in the rightmost 
byte of the attribute bytes of the post-open DTF is set 


on to indicate device allocation. 


@ The address of the first DTF allocated is returned in 
register 2. 


Note: \f you are using telecommunications, $ALOC must 


not be issued while a telecommunications operation is in 
process. 


The format of the $ALOC macro instruction is: 


[Name] $S$ALOC [DT F-address] 


DTF-address specifies the address of the high-order byte of 
the DTF being allocated. If this operand is not entered, 
the address of the DTF is assumed to be in register 2. 


Prepare An !/O Device (SOPEN) 


This macro instruction prepares an input/output file for 
data transfer. The file to be prepared (opened) must 
previously have been allocated by using the allocate macro 
instruction. Depending on the device, one or more of the 
following functions are performed for each file opened. 


e The post-open DTF is formatted (see Figure 12). 


@ Pre-open DTF information is preserved in the format-1 
label as required. 


e Input/output buffers, index buffers, and IOBs are 
formatted. 


e Buffers are initialized as required. 


e Cards are positioned at the wait station for card output 
files. 


@ The index area on disk for indexed files and the data 
area on disk for direct files are formatted as required. 


e@ Diagnostics are performed to ensure that: 


1. The access method and the file organization are 
compatible. 


2. | The volume and file are mounted on the correct 
disk or tape drive. 


Note: More than one DTF can be opened at one time by 
chaining the DTFs. To chain DTFs, you must enter the 
address of the next DTF in the DTF you are building. The 
last DTF in a chain has X‘FFFF’ entered in place of the 
address. See $DTFU, $DTFD, $DTFT and $DTFK. 


Input The pre-open DTF and format-1 label are input to 
the open routine. Before the open macro instruction is 
issued, you must be sure to have the device allocated by 
previously issuing the allocate macro instruction. Also, if 
you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $OPEN macro instruction. You must also consider the 
following in preparing the DTF: 


@ Thedisk access method must be compatible with the 
disk file organization of the file being opened. 


e@ The access method must be compatible with the access 
method of the same file opened in the other program 
level or for an inquiry program (see Ro//out). 


@ Therecord length and key length must be specified 
correctly. 


Pre-Open Conditions 


1. Unformatted disk files 
are present for output 
files. 


Post-Open Conditions 


1. Formatted disk files are 
created. 


2. 1/O buffers, 1OBs, and 
various work areas are 
formatted. 


2. The I/O buffer is in the 
unformatted mode. 


. A bit is set on in the 
DTF attribute bytes to 
indicate an opened file. 


Figure 12. Comparison of Pre-Open and Post-Open DT Fs and 
Data Areas 


Output The open routine returns control to your program 
when the requested file has been opened. The following 
output is produced: 

e Thecontents of register 1 are restored. 


e The format-1 labels are updated. 


e Bit 7 in the rightmost attribute byte in the post-open 
DTF is set on to indicate the file has been opened. 


@ The device code (displacement 0 in the DTF) is altered 
to indicate the unit on which the file resides. 


e The buffers are initialized. 


e The address of the last DTF opened is returned in 
register 2. | 


The format of the $OPEN macro instruction is: 


[Name] $SOPEN [DT F-address] 


DTF-address specifies the address of the leftmost byte of 
the DTF for the file to be opened. If this operand is not 
entered, it is assumed that the address is in register 2. 
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| Generate a Check List (SCKL) 


This macro instruction creates an entry for a check list. It 
does not generate executable code. The check list identi- 
fies DTFs to be checked for I/O completion by the $CHK 
macro instruction. The following types of DTFs can be 
identified in the check list: 


e@ 5471 Printer-Keyboard (console) 

e Binary Synchronous Communications (BSC) 

@ Multiple Line Terminal Adapter (MLTA) 

For a description of the check list entries, see Figure 13. 


For a description of BSC, see /BM System/3 Multiline/ 
Multipoint Binary Synchronous Communications 
Reference Manual, GC21-7573; for a description of MLTA, 
see /BM System/3 Multiple Line Terminal Adapter RPQ 
Program Reference and Component Description Manual, 
GC21-7560. 


All the check list entries that are to be tested by the same 
$CHK macro instruction must be issued consecutively. 
The same DTF may be in the list more than once. The 
check list entries that are generated are contiguous in main 
storage. You can then issue the $CHK macro instruction 
to test the entire list, by specifying the first entry in the 
list; or begin testing anywhere in the list, by specifying the 
label of one of the later entries. 


If a console DTF is to be used for both the request key and 
data input functions at one time, you must specify two 
check list entries for that DTF (for one entry, specify 
REQK-Y; for the other entry, either omit the REQK 
operand or specify REQK-N). 


Note: The address you specify in the $CHK macro instruc- 


tion identifies the beginning of the check operation. Any 
entries occurring earlier in the list are ignored in that 
operation. 


The format of the $CKL macro instruction is: 


DTF-address [,SKIP-Y/N] 
[,REQK-Y/N] [,RTN-Y/N] 


[, LAST-Y/N] 
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DTF-address specifies the symbolic address of the leftmost 
byte of the DTF for which this check list entry is oeing 
created. 


SKIP-Y or N specifies whether this entry should be skipped 
when the check list is scanned. If this operand is omitted, 
N (no) is assumed. If Y is specified, you must update the 
checklist entry before you can check the DTF specified in 
this macro instruction. You can access the skip indicator 
in the entry by using the name specified on the macro in- 
struction. 


REQK-Y or N specifies whether the check routine should 
determine whether the Request Key has been pressed on 
the 5471 Printer-Keyboard. If this operand is not specified, 
N (no) is assumed. You can change this entry during pro- 
gram execution. 


Note: The keyword CONS-Y or N has been replaced by 
REQK (above); if you have coded CONS, however, the 
same function will be performed. 


RTN-Y or N specifies whether you want control returned 
to your program even if no I/O operation is complete. 
This operand is valid only for the first entry in the check 
list. If this operand is not entered, N (no) is assumed. 


LAST-Y or N specifies whether this is the last entry in the 
check list. LAST-Y (yes) must be specified for the last 
entry. If this operand is omitted, N (no) is assumed. 


| Disp Field Description 


Flag byte: 


X‘80’—Skip this entry 

X‘'40'—Request key should be checked 

X‘20’—This is the last entry in the check list 

X‘'10'—Return control to the user if no 1/O com- 
pletion is found (significant only in the 
first entry of a check fist) 3 


Address of the DTF for this entry 


Figure 13. Check List Format 


| Check for 1/0 Completion ($CHK) 


This macro instruction generates the linkage required to 
use the check routine. You must issue the $CHK macro 
instruction for each BSC or MLTA get, put, read, write, or 
online test request. For a description of BSC macro in- 
structions, see /BM System/3 Mul!tiline/Multipoint 

Binary Synchronous Communications Reference Manual, 
GC21-7573. Fora description of MLTA macro instruc- 
tions, see /BM System/3 Multiple Line Terminal Adapter 
RPQ Program Reference and Component Description | 
Manual, GC21-7560. 


You can also use the check routine to test for completion 
of console operations and to determine whether the request 
key on the console has been pressed. However, if your 
program does not use BSC or MLTA, you will use less main 
storage by using the wait function provided with the 
$PKBU macro instruction. 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $CHK macro instruction. 


Check Routine Operation: The check routine tests for 
completion of an 1/O operation by examining the DTFs 
identified in the check list - see Generate a Check List 
($CKL). \f an |/O operation is complete, the completion 
code is set in the DTF, and the address of the DTF is 
returned in register 2 to the calling program. No 
subsequent DTFs in the list are tested. 


When a REQK-Y entry is encountered in the list, the check 
routine tests the inquiry request bit in the system com- 
munication region to determine whether the request key 


was pressed on the console. If it was, the completion code © 


in the console DTF is set to X‘50’, the DTF address is put 
in register 2, and control is returned to your program. 


If no 1/O completion is found by the end of the check 
list, one of the following actions is taken. 


1. Control is returned to your program with the address 
of the last DTF in the list register 2 if: 


@ Each entry in the list is inactive, closed, or has the 
skip indicator on (X‘57’). 


e RTN-Y was specified in the $CKL macro instruction 
that created the first entry in the check list (X‘56’). 


2. Control is not returned to your program. Instead, 
the check routine issues a halt ({ ] displayed on the 
console stick lights) and waits for an I/O operation 
to be completed. When the operation is complete, 
the completion code is set in the DTF and the ad- 
dress of the DTF is returned in register 2. 


Note: \f the only operations pending are on the console, 
you must issue the $CHK macro instruction again to reset 
the [ ] halt. 


The format of the $CHK macro instruction is: 


[Name] $CHK | [CKL-address] 


CKL-address specifies the symbolic address of the first 
entry in the check list. You may also begin at a subsequent 
point in the check list by specifying the symbolic address 
of a later entry. If this operand is omitted, the address is 
assumed to be in register 2. 


Note: The address you specify identifies the beginning of 
the check operation. Any entries occurring earlier in the 
list are ignored in that operation. 
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Prepare a Device for Termination ($CLOS) 


The close macro instruction prepares a device for job ter- 

, mination. The routine returns post-open DTFs to their pre- 
open state and updates file labels to reflect the current file 
status. For devices other than disk or tape, only the entries 
related to the requested functions are restored. If you will 

-need to use the data in register 2 at a later time, you should 
save the contents of that register before issuing the $CLOS 
macro instruction. 


Input to the close routine consists of the post-open DT F 
and the format-1 labels. The allocate and open macro in- 
structions must have previously been issued. 


Output created by $CLOS is returned to your program 
when control is returned. The output consists of: 


e The contents of register 1 is restored. 


e The post-open DTFs are reininialized to the pre-open 
state. 


e@ Any pending operations for unit record devices are 
performed. 


@ The format-1 label for disk is updated to indicate cur- 
rent file status. 


e The buffer contents scheduled for disk or tape output 
and disk update operations are written. 


e The data and index are written to disk, and an indicator 
is set if key sorting is required at end-of-job for output 
files and file additions. 


@ Tape trailer labels are read or written. 


Note: More than one DTF can be closed at one time by 
chaining the DTFs. To chain DTFs, each DTF to be closed 
must contain the address of the next DTF in the chain. The 
last DTF in a chain has X‘FFFF’ entered in place of the 
address. See $DTFU, $DTFD, $DTFT, and $DTFK. 


The format of the $CLOS macro instruction is: 


[Name] $CLOS [DT F-address] 


DTF-address specifies the address of the leftmost byte of 
the DTF to be closed. If this operand is not entered, the 
address is assumed to be in register 2. 
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Unit Record Support 


Five macro instructions are provided for performing |/O 
operations on unit record devices. They are: 


e $DTFU—define the file (DTF) for unit record 
e $DTOU—define the file (DTF) offsets 
e $GPU-—get or put for unit record 


e $PKBU—construct an |/O interface to the printer- 
keyboard 


e $PRNT—print a message on the halt/syslog device 


The DTF and DTF-offsets macro instructions are used 
together. The DTF macro instruction generates a DTF 
control block and initializes it to values you specify. The 
DTF-offsets macro instruction generates equates to give 
unique labels to the offsets in the DTF. 


The remaining macro instructions are used to perform the 
actual input or output operations. 


Define the File for Unit Record (SDTFU) 


Through the DTF, you provide information about a file 

to the allocate and open routines. The pre-open and post- 
open DTFs for the various unit record devices are explained 
in Appendix B: Define the File Control Blocks. 


The format of the $DTFU macro instruction is: 


DEV-code, FT YP-code, P!lOB-address 
[, UP-mask] [,DIO-Y/N] [,HUC-Y/N] 
[,RECL-number] [,CHN-address] 
[,RCAD-address] [,RDA1-address] 
[,RDA2-address] [,PUA1-address] 


[,PTA1-address}] [,OVFL-number] 
[,PG-number] [,MSKP-number] 
[,REPLY-number] [,SPACE-number] 
[,FREQK-Y/N] [,FILL-Y/N] 
[,.CHK-Y/N] [,RTN-Y/N] 


Note: PIOB required on Model 12 only. 


DE V-code specifies the device. This is a required operand. 
One of the following codes must be entered; however, the 
same code cannot be specified in more than one $DTFU 
macro instruction in the same program. 


Code Meaning 


MEFCU or MFCU1 
MFCU2 
PRNTR or PRNTR1 


MFCU primary hopper — 
MFCU secondary hopper 
5203 printer (left carriage) or 
1403 printer 


PRNTR2 5203 printer (right carriage) 
D1442 1442 card read/punch 
CONSOL 5471 printer-keyboard 


FTYP-code specifies the type of file. This is a required 
operand. One of the following codes must be entered. 


Code Meaning 


| Input: MFCU, 1442, or console 
read 


Por P1 Output: MFCU or 1442 punch, 
printer, or console write 

Cor C1 Combined: MFCU or 1442 read 
and punch or console write to 
operator with reply 

P2 | Output: MFCU print 

P3 Output: MFCU punch and print 

C2 Combined: MFCU read and print 

C3 Combined: MFCU read, punch, 


and print 


PIOB-address specifies the address of the leftmost byte of 
the printer 1|OB. The size of the printer 1OB is 23 bytes. 
This parameter is required on the Model 12 only and is 
not valid on the Model 10. 


UP-mask specifies the mask for testing the external indi- 
cators set in the // SWITCH statement. For example, to 
set on bits 0, 3, 5, and 7, you would enter UP-10010101. 
If this operand is not entered, a mask of zero is assumed. 


DIO-Y or N specifies whether two physical input/output 
buffers are supplied. If this operand is not entered, N (no) 
is assumed. Y (yes) can be specified only for card input 
files. 


HUC-Y or N specifies whether a halt should be issued 
when an unprintable character is detected in the print 
record. If this operand is not entered, N (no) is assumed. 
This operand applies to line printer files only. 


RECL-number is a decimal value specifying the logical 
record length for a 1442 punch file, a line printer file, or a 
console input/output file. If this operand is not entered, 
zero is assumed and the value must be updated in the DTF 
before the output operation may be performed. 


CHWN-address specifies the address of the next DTF in the 
forward chain. If this operand is not entered, the end-of- 
chain ID (X‘FFFF’) is assumed. 


Note that DTFs may be chained to permit opening of more 
than one DTF with one open request. See Prepare An //O 
Device (SOPEN) for more information on chaining. 


RCAD-address specifies the address of the leftmost byte of: 


@ The logical record when using the output function for 
MFCU, 1442, or line printer files. 


e The buffer area for all console operations. This is the 
only input/output area specified for console files. 


This address must be different from the address specified 
for either PUA1 or PTA1. If this operand is not entered, 
X‘FFFF’ is assumed and you must update this value in the 
DTF before performing the output operation. 


Output records for unit record devices are built or altered 
in the work area pointed to by RCAD. These records are 
called logical records. For devices other than the console, 
data management routines move the record to the physical 
buffer (PUA1 or PTA1) before performing the output 
operation. 


RDA 1-address specifies the address of the leftmost byte 
of the first physical input buffer. If this operand is not | 
entered, X'FFFF’ is assumed and you must update it in 
the DTF before issuing the input command. The address 
must be on a 128-byte boundary. 


RDA2-address specifies the address of the leftmost byte of 
the second physical input buffer when dual buffers are used. 
If this operand is not entered, X‘FFFF’ is assumed and you 
must update this value before using dual buffering in an in- 
put operation. The address must be on a 128-byte boundary. 


PUA T1-address specifies the address of the leftmost byte of 
the physical punch buffer. If this operand is not entered, 
X‘FFFF’ is assumed and you must update it before per- 
forming a punch operation. The address must be on a 128- 
byte boundary. 


PTA 1-address specifies the address of the leftmost byte of 
the physical print buffer for print files. If this operand is 
not entered, X‘'FFFF’ is assumed and you must update the 
value before an output operation to the printer is issued. 
This address must be of a 256-byte area aligned on a 256- 
byte boundary for MFCU print operations. For line- 
printer operations, the area must be aligned on a X‘7C’ 
boundary (the first 124-byte boundary after a 256-byte 
boundary). 
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OVFL-number is a decimal number specifying the overflow 
line for line-printer output files. If this operand is not 
entered, zero is assumed and 60 is inserted by the open 
routines. 


PG-number is a decimal value specifying the total number 
of lines on the form used by the printer file. The number 
must not be greater than 112; if the operand is not entered, 
66 is assumed. 


MSKP-number specifies the maximum line number used in 
the skip-before or skip-after byte of the line-printer DTF. 
If this operand is not entered, zero is assumed. 


Note: The generated code from the $GPU macro instruc- 
tion does not perform carriage control for printer files. To 
prevent overprinting, you must set the space before, space 
after, skip before, skip after bytes in the printer DTF to 
perform the spacing you desire. 


REPLY-number specifies the decimal length of the 
operator’s reply for a write-to-operator-with-reply opera- 
tion on the console. If this operand is not entered, zero is 
assumed and you must update the entry before the opera- 
tor’s reply can be received. | 


SPACE-number is specified only for console files. It isa 
two-digit decimal number that indicates the number of 
lines to be spaced before and after the console operation. 
The first digit specifies the space before; the second, the 
space after. If only one digit is specified, it is assumed to 
be the space-after value. If this operand is not entered, 
zero is assumed. 


Note that at least one space-before is performed for all 
console operations. | 


REQK-Y or N specifies whether the request key must be 
pressed before an input record is accepted from the con- 
sole. If this operand is not entered, N (no) is assumed. 
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FILL-Y or N specifies whether the operator must fill the 
input or reply record for console files. If this operand is 
not entered, N (no) is assumed. 


CHK-Y or N specifies whether the console operation must 
be completed before control is returned to your program. 
N indicates a check for completed operation will be per- 
formed at the time of the operation; the console operation 
must be completed before control returns. Y indicates no 
check will be performed at the time of the operation; 
control returns directly after the console operation is 
started. See Construct an Interface to the Printer- 
Keyboard ($PKBU) and Check for 1/0 Completion (SCHK) 
for more information on console operations. If this 
operand is not specified, N is assumed. 


RTN-Y or N is specified only if CHK-Y was specified for a 
console operation. This operand specifies the type of check 
Operation to be performed. If Y is specified, the console 
operation is checked for completion and control! is returned 
to your program with a completion code to indicate 
whether the operation was completed. If N is specified, 

the console operation is checked for completion and a 

wait is performed if the operation is not completed. 
Control is not returned to your program until completion 
occurs. If this operand is not specified, N is assumed. 


If the entry specified in the CHEK parameter in the $DTFU 
or $PKBU macro instruction is not the same as the entry 
specified in the RTN parameter of the $CHK macro in- 
struction, control does not return from a console operation 
until the operation has been completed. For more infor- 
mation on specifying the check operation for the console, 
see Construct an Interface to the Printer-Keyboard 
($PKBU). 


Unit Record DTF Offsets (SDTOU) 


This macro instruction generates a list of equates to estab- 
lish labels in the unit record DTFs. These labels are offsets 
from the beginning of the DTF and are used as displace- 
ments from the beginning of the DTF when you must 
access the DTF. The labels assigned by this macro instruc- 
tion are shown with the respective DTFs in Appendix B: 
Define the File Contro! Blocks. You must not issue this 
macro instruction more than once for each unit record 
device. 


The format of the $DTOU macro instruction is: 


| | $DTOU | [DEV-code] | 


Note: You do not assign a name to the $DTOU macro 
instruction. 


DE V-code specifies the device described in the related 
DTF. If the operand is not entered, MFCU is assumed. 
The valid codes are: 


Code Meaning 

MFCU MFCU 

PRNTR Line printer 

D1442 1442 Card Read/Punch 
CONSOL 


5471 Printer-Keyboard 


Get or Put for Unit Record ($GPU) 

You can use this macro instruction in one of three ways: 
e Get data from an input file 

e Put data to an output file 

e Get data from and put data to a combined file 


You may write your own routines to handle special condi- 
tions, such as: 


e Anend-of-file routine for input files 
e Anerror handling routine 
e An overflow routine for printer files 


This macro instruction requires that you use the $DTOU 
macro instruction to establish the labels for the unit 

record DTF. If you will need to use the data in register 2 
at a later time, you should save the contents of that register 
before issuing the $GPU macro instruction. 


Note: The generated code from the $GPU macro instruc- 
tion does not perform carriage control for printer files. To 
prevent overprinting, you must set the space before, space 
after, skip before, skip after bytes in the printer DTF to 
perform the spacing you desire. 


The format of the $GPU macro instruction is: 


ERR-address,MODUL-label 
[,OPC-code] [,DEV-code] 
[,DTF-address] [,EOF-address] 


[,OVRTN-address] 
[,DEFER-Y/N] 
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ERR-address specifies the address of a routine you supply 
to handle permanent error conditions encountered during 
the input or output operation. This operand is required. 


In your error handling routine, you must determine 
whether to cancel the program or continue processing with 


Note: In order to conserve main storage, you should 
determine whether you can use the same module for 

more than one function rather than a new module for 
each function. For example, if you want to read, punch, 
and print, specifying $$MFFF would use less main storage 
than using $$MFRD, $$MFPU, and $$MFPR. 


the next record. You may wish to determine the type of | 


error encountered before canceling or continuing the pro- 
gram. The type of error is indicated in the DTF. (See 
Appendix B: Define The File Control Blocks.) 


OPC-code indicates the input/output operation to be per- 
formed. If this operand is not entered, READ is assumed. 
The following codes may be specified: 


Code Meaning 

MODUL-label provides the name of the system data 

management routine to be used for the input/output READ Read from the MFCU or 1442 

operation. Figure 14 shows the names of the system Card Read/Punch 

routines and the functions they provide. You must iden- RDPRT Read and print on the MFCU 

tify the label used in this operand by specifying it as the RDPCH Read and punch on the MFCU 

operand of an EXTRN instruction in your program. This RDPP Read, punch, and print on the MFCU 

operand is required. PUNNF Punch, with no feed, on the 1442 
PUNCH Punch on the MFCU or 1442 
PUPR Punch and print on the MFCU 
PRINT Print on a line printer or MFCU 
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1442 
5203/1403 


Console 


System 
Module 


$$MFRD 


$$MFPU 


$S$MFPR 


$$MFRU 


$$MFRP 


_ $SMFPP 


$$MFFF 


$$ARFF 
$$LPRT 


$$COAM 


This operand is used with the MODUL operand to perform 
the operation. | 


Reads cards from either hopper. 
Punches cards from either hopper. 


Prints on cards from either hopper. 


Reads and/or punches cards from either hopper. 


Reads from and/or prints on cards from either hopper. 


Punches and/or prints cards from either hopper. The defer operation may 
also be used. 


Supports the following functions: 
Read 
Punch 
Print 
Punch deferred 
Print deferred 
Feeds, reads, and punches cards. 


Performs printing, skipping, and spacing as requested through the DTF. 


Performs input and output operations on the printer-keyboard. 


Note: These modules are described in more detail in /BM System/3 Models 4, 6, 8, and 10 Data Management and 
Input/Output Supervisor Logic Manual, SY21-0512. 


Figure 14. System Unit Record Module Names and Functions 


Note 7: When you issue a combined command involving a 
read, the output operations are performed on the card 
presently at the wait station and before the next card is 
read. Therefore, before issuing the first combined com- 
mand, you must issue a READ command to get the first 
input record and advance it to the wait station. 


Note 2: For any read operation, the logical record address 
(specified by RCAD in the DTF) is replaced by the current 
input buffer address. Before a combined file is used for 
output, you should ensure that the logical record address 
(offset $RDLRA for the MFCU or $FDLRA for the 1442) 
points to the logical record for the output operation. This 
can be done by using the input buffer as the logical record 
or by storing the logical record address at the offset before 
performing the output operation. | 


DE V-code specifies the device for the file. If this operand 
is not entered, MFCU is assumed. The following codes 
may be specified: | 


Code Meaning 


MFCU or MFCU1 
MFCU2 
PRNTR or PRNTR1 


MFCU, primary hopper 
MFCU, secondary hopper 
5203 printer (left carriage) or 
1403 printer 

5203 printer (right carriage) 
1442 card read/punch 


PRNTR2 
D1442 


DTF-address specifies the address of the DTF for the file. 
If this operand is not entered, the address is assumed to be 
in register 2. 


EOF-address is used only with the input function. This 
operand provides the address of a routine you have written 
that is to receive control when end-of-file is reached. 


OVATN-address is required for line printer output files. It 
specifies the address of your routine that handles the over- 
flow condition. 


DEFER-Y or N is used only with output operations to the 
MFCU. This operand enables you to print one record ona 
card and punch a different record in the same card. To do 
this, you first issue the $GPU macro instruction for either 
a print or a punch with DEFER-Y. You then modify the 
logical record as needed to a different format and issue 
another $GPU macro instruction for the remaining opera- 
tion with DEFER-N. Both operations are then performed. 
If this operand is not specified, N (no) is assumed. 


Construct an Interface to the Printer-Keyboard ($PKBU) 


This macro provides access to the 5471 Printer-Keyboard 
(console). The following functions are provided: 


e Get a record 

@ Puta record 

e@ Write to operator with reply 

To use this macro instruction, you must issue the $DTOU 
macro instruction to establish the labels for the unit 
record DTF. If you will need to use the data in register 2 


at a later time, you should save the contents of that register 
before issuing the $PKBU macro instruction. 


The format of the $PKBU macro instruction is: 


[OPC-code] [,DTF-address] 
[,ERR-address] [,RECL-number] 
[,REPLY-number} [,SPACE-number] 
[,RCAD-address] [,REQK-Y/N] 
[,FILL-Y/N] [,EOF-address] 
[,CHK-Y/N] [,RTN-Y/N] 


OPC-code specifies the operation to ve performed. If this 
operand is not entered, SET is assumed. The operation 
codes are: 


Code Meaning 

GET Get a record from the console 

PUT Put a record to the console 

WTOR Put a record to the console and 
get a reply 

SET Use the operation previously 


defined for this DTF. If there is no 
previous operation established, PUT 
is assumed | 


DTF-address is the address of the high-order byte of the 
DTF to be used in this operation. If this operand is not 
specified, the address is assumed to be in register 2. 
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ERR-address specifies the address of your error routine 
which receives control whenever a permanent error is 
detected on the console. If this operand is not entered, 
no checks are performed for permanent error conditions. 


This operand should not be used when CHK-Y is specified. 


RECL-number specifies the decimal length of the logical 
record. If this operand is not entered, the record length 
previously established in the DTF is used. 


REPLY-number specifies the decimal length of the reply 

to be received during a WTOR operation. If this operand 

is not entered, the reply length previously established in the 
DTF is used. 


SPACE-number is a two-digit decimal number that indi- 
cates the number of lines to be spaced before and after the 
console operation. The first digit specifies the number of 
lines to space before; the second digit specifies the number 
of lines to space after the operation. If only one digit is 
specified, it is used as the space-after value. If this operand 
is not entered, the spacing values previously established in 
the DTF are used. In any case, the console always per- 
forms at least one space before for each operation. 


RCAD-address specifies the address of the leftmost byte 
of the buffer area used. If this operand is not entered, the 
address previously established in the DTF is used. 


REQK-Y or N specifies whether the request key must be 
pressed before an input record can be accepted from the 
console. If the operand is not entered, the entry previously 
established in the DTF is used. 


Note 7: When REQOK-Y is specified, the program must be 
identified as an inquiry program (a program that calls roll- 
out) when the program is linkage-edited. 


Note 2: When FTYP-C is specified, in the $DTFU macro 
instruction, or when OPC-WTOR is specified in the $PKBU 
macro instruction, REQK-Y is ignored. 


FILL-Y or N specifies whether the input or reply record 
from the operator must be the exact length requested. If 
this operand is not entered, the entry previously established 
in the DTF is used. 
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EOF -address is the address of the routine in your program 
that is to receive control when an end-of-file record is read 
from the printer keyboard. This operand should not be 
used when CHK-Y is specified. 


CHK-Y or N specifies whether the console operation must 
be completed before control is returned to your program. 
N indicates a check for completed operation will be per- 
formed; the console operation must be completed before 
control returns. Y indicates no check. Control returns 
directly after the console operation is started, with a com- 
pletion code of X‘00’ to indicate the operation has not 
been completed. The completion code is located in the 
printer-keyboard post-open DTF at label $CDCMP. If 
FTYP-C was specified in the $DTFU macro instruction or 
if OPC-WTOR was specified in the $PKBU macro instruc- 
tion, control is not returned to your program until the out- 
put operation is completed. If this operand is not specified, 
the option established in the DTF is used. See Note in the 
discussion of RTN-Y or N. 


RTN-Y or N is specified only if CHK-Y was specified for a 
console operation. This operand specifies the type of 
check operation to be performed. If Y is specified, the 
console operation is checked for completion, and control . 
returns to your program. The completion code in the DTF 
remains X‘00’ until the operation is completed. You must 
check the completion code in your program to determine 
whether it has changed. If N is specified, the console 
operation is checked for completion, and a wait is per- 
formed if the operation is not completed. Control is not 
returned to your program until completion occurs. The 
completion code reflects the outcome of the operation. 

If this operand is not specified, the option established in 
the DTF is used. 


If the entry specified in the CHEK parameter in the $DTFU 
or $PKBU macro instruction is not the same as the entry 
specified in the RTN parameter of the $CHK macro instruc- 
tion, control does not return from a console operation until 
the operation has been completed. 


Note: When CHK-Y is specified for a console operation, 
you must determine that the operation has been completed 
before you can initiate another console operation. You can 
do this in two ways: 


1 Recall the operation, using the check function in the 
console macro instruction. 


2. Issue the $CHK macro instruction, using the associ- 
ated check list macro instruction (S$CKL). 


The operation must be tested at least once to determine that 
the operation was completed. 


You can recall an operation by issuing the same macro in- 
struction again or by issuing another $PKBU instruction 
with no operands specified. If no operands are specified, 
the address of the DTF must be in register 2. When the 
Operation is recalled, the CHK option is ignored and the 
RTN option is used to determine the type of check 
requested by the recall. 


For more information on using the check routine to test 
completion, see Construct a Check List (SC KL) and Check 
for 1/0 Completion (CHK) 


Print a Message (SPRNT) 


This macro instruction prints a message on the halt/syslog 
device using the halt/syslog routines. This instruction 
provides a printed message with wait and no halt. If you 
will need to use the data in register 2 at a later time, you 
should save the contents of that register before issuing the 
$PRNT macro instruction. © 


Note: \f the halt/syslog device has been allocated to your 
program through another DTF, or if the length of the 
message is greater than 132, no message is printed. Control 
is returned directly to your program. 


The format of the $PRNT macro instruction is: 


[Name] $PRNT NAME-address,_LEN-number _ 


NAME.-address specifies the address of the leftmost byte of 
the message you want printed. This operand is required. If 
the SYSLOG device is a line printer, the message must be 
aligned on a X‘/7C’ boundary. 


LEN-number is a decimal number specifying the length of 
the message to be printed. This operand is required. 


Disk Device Support 


This section describes the macro instructions that support 
disk devices. The following functions are provided: 


e@ Build a pre-open DTF for disk and assign its offsets. 


e@ Build an input/output block (IOB) for disk and assign 
its offsets. : 


e Build the interfaces required to get input records from 
a disk device via a get or a read. 


e Build the interfaces required to put output records to a 
disk: device via a put or a write. _ 


e@ Build the routine to wait for disk completion. 


The disk DTFs provide information to the disk data 
management, and the disk IOBs provide information to 
the input/output supervisor routines that perform the 
input or output operations. These operations are pro- 
vided through the disk support macro instructions. 
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Define the File for Disk (SDTFD) 


The DTF provides information needed to allocate and 
open a file on the disk device. This macro instruction 
generates the code that builds the disk DTF. See 
Appendix B: Define the File Control Blocks for a descrip- 
tion of the pre-open and post-open disk DTFs. 


The format of the $DTFD macro instruction is: 


AC-code, RECL-number, 
NAME.-filename,|O-address, 
BLKL-number [,DISK-5444/5445] 
[,UP-mask] [,BUFNO-1/2] 
[LMVE-N/Y] [,LIM-N/Y] 


[,ORD-N/Y] [,BIN-N/Y] 
[,CHN-address] [,RCAD-address] 
[,ENT-number] [,MSTX-address] 
[,MVFEN-number] [,KEY L-number] 
[,KEYD-number] [,KEYA-address] 
[,MVF T-address] 


AC-code specifies the access method used for the file. This 
operand is required. The codes and their meanings are as 
follows: 


Code Access Method 

CA Consecutive add 

CG Consecutive get 

CO Consecutive output 

CU Consecutive update 

DG Direct get 

DO Direct output 

DU Direct update 

IA Indexed add 

lO Indexed output 

IR Index random get 

IRA Index random add 

IRU Indexed random update 

IRUA Indexed random update and add 
IS Indexed sequential get 

ISA Indexed sequential add 

ISU indexed sequential update 

ISUA Indexed sequential update and add 


RECL-number specifies the decimal length of the logical 
record. This operand must be specified. 


NAME-file name specifies the name of the file. The name 


may be eight characters or less in length. This operand 
must be specified. 
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/O-address provides the address of the leftmost byte of an 
area in main storage reserved for all buffers and IOBs for 
the access method. OPEN allocates buffers and builds the 
IOBs. This operand must be specified. The amount of | 
main storage required is: 


[(BLKL+X) times BUFNO] 


plus (256 + X) if the access method is indexed; | 
plus (256 + X + one key length) if the access method is 
indexed multivolume; 
plus (Y) if the file type is multivolume and the access 
method is indexed random. 
where: 
X = 22 bytes when using the 5444; 
26 bytes when using the 5445 
Y = 32 bytes for 5444 multivolume random input or 
update; 7 
16 bytes for 5445 multivolume random input or 
update; | 
88 bytes for 5444 multivolume random add or 
update and add; 
52 bytes for 5445 multivolume random add or 
update and add 


BLKL-number specifies the number of bytes in the buffer. 
The minimum number can be determined as follows: 


e If the record length is less than or equal to 256 and 
evenly divisible into 256, the buffer length is 256. 


e If the record length is greater than 256 and a multiple 
of 256, the buffer length is equal to the record length. 


e@ If the record length is not evenly divisible into 256 and 
not a multiple of 256, the buffer length is the multiple 
of 256, next higher than the record length plus 255. 


Note: These buffer lengths are minimum lengths. Larger 
lengths may be specified, but they must be in multiples of 
256. 


The following access methods can always operate ina 
minimum of a 256-byte buffer: 


Consecutive output 

Consecutive add 

Consecutive output multivolume 
Consecutive add multivolume 
Consecutive input 

Consecutive input multivolume 
Indexed output 

Indexed output and add 

Indexed output multivolume 
Indexed sequential input 

Indexed sequential input with limits 
Indexed sequential input multivolume 


DISK-5444 or 5445 specifies whether the disk device is 
the IBM 5444 Disk Storage Drive or the IBM 5445 Disk 
Storage. If this operand is not specified, 5444 is assumed. 


UP-mask specifies the settings of the external (// SWITCH 
statement) indicators used for conditionally opening files. 
The code must be specified as eight binary bits. For 
example, to set on bits 0, 3, 5, and 7, you would enter 
UP-10010101. If this operand is not entered, zeros are 
assumed. 


BUFNO-1 or 2 allows you to specify either one or two 
buffers for the file. You can use two buffers only with | 
consecutive access methods. All consecutive access 
methods allow dual buffering except the consecutive 
update and consecutive update multivolume. If this 
Operand is omitted, one buffer is assumed. 


MVF-N or Y specifies whether the access method is multi- 
volume. If this operand is omitted, N (no) is assumed. 


LIM-N or Y is specified only for indexed sequential get 
and indexed sequential update. It specifies whether the 
sequential access is within limits. If this operand is not 
entered, N (no) is assumed. 


ORD-N or Y specifies whether an ordered load is to be used 
with the indexed output access method. This operand can 
be specified only with the indexed output access method. 
ORD-Y must be specified for indexed multivolume output 
access methods. If this operand is not entered, N (no) is 
assumed. 


BIN-N or Y is specified only with the direct output, direct 
get, and direct update access methods. Y (yes) indicates 
direct binary relative record numbers; N (no) indicates 
direct decimal relative record numbers. If this operand is 
omitted, N is assumed. 


CHWN-address indicates the address of the next DTF in the 
chain of DTFs. If there is no DTF chain, the operand is 
omitted and X‘FFFF’ is assumed. 


RCAD-address specifies the address of the leftmost byte of 
the logical record. If this operand is not entered, X‘0000’ 
is assumed. Depending on the disk access method being 
used for an input operation, either move mode or locate 
mode is used. If move mode is used, the record is provided 
at the address specified in the RCAD parameter. If locate 
mode is used, the address of the input record is contained 
at label SDFWKB in the DTF. For information on the 
mode used by the different access methods, see Figure 16. 


ENT-number specifies the number of entries in the master 
track index. This operand is specified only for indexed 
random or indexed add access methods. The number of 
entries in the master track index is one less than the 


‘number you specify in this operand for 5445 single volume 


files (two less for 5445 multivolume files), when the 
following access methods are used: 


@ Indexed add 
@ Indexed random input and add 


e Indexed random input, update, and add 
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MST X-address specifies the address of the leftmost byte 
of the master track index in main storage. This operand 
must be specified for indexed random and indexed add 
access methods. You must allocate space in main storage 
for the master track index. The length of the master 
track index is determined by the following formulas: 


~@ For single volume random input or update access methods: 


Length = ENT (key length + 2) 


@ For single volume random add or update and add access 
methods, 5444/5445: 
Length = ENT (key length + 2) 
3340: 
Length = ENT (key length + 2) + 2 (key length) 


@® For multivolume random input or update access methods, 
5444: 
Length = ENT (key length + 2) 
ENT must be equal to or greater than 4. 
5445/3340: 
Length = ENT (key length + 2) 
ENT must be equal to or greater than 2. 


@® For multivolume random add or update and add access 
methods, 5444: 
Length = ENT (key length + 2) 
ENT must be greater than or equal to 4. 
5445: 
Length = ENT (key length + 2) 
ENT must be greater than or equal to 2. 
3340: 
Length = ENT (key length + 2) + 2 (kev length) 


MVFN-number indicates the number (in hexadecimal) of 
volumes for a multivolume direct access method. This 
Operand must be specified for these access methods. 


KEY L-number specifies the length of the key field and 
must be used for all indexed access methods but no others. 
The key field length can be no more than 29 bytes. 


KE YD-number is entered for all indexed access methods. 
It indicates the displacement into the record of the right- 
most byte of the key field. The displacement of the first 
byte in the record is zero, the second byte is one, and so 
on. 


KE YA-address specifies one of the following: 


@ Main storage address of the leftmost byte of the key 
field for indexed random access methods. 


@ Main storage address of the leftmost byte of the 
relative record number field for direct access methods. 
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@ Main storage address of the leftmost byte of the save 
area for current and last keys for indexed sequential 
add access methods. 


@ Main storage address of the leftmost byte of the save 
area for high and low keys for indexed sequential with 
limits access methods (LIM-Y). 


This operand is required for these access methods. 


You must allocate the main storage space for the fields. 
The amount of space required is: 


@ The number of bytes in the key field for indexed 
random access methods. 


@ 23 bytes for direct access methods with decimal keys. 
The decimal key is located in the rightmost 15 bytes 
of the field. 


@ 8 bytes for direct access methods with binary keys. 


The binary key is located in the rightmost 3 bytes of 
the field. 


@ Two times the key length for indexed sequential add 
or indexed sequential with limits access methods. The 
low key is located in the left half of the field, the high 
key in the right half. 


MVF T-address must be specified for all multivolume 
direct files, and only for the access methods used with 
these files. This operand specifies the address of the left- 
most byte of the table of extents used for the access 
methods used with these files. You must allocate main 
storage space for the table. The number of bytes allocated 
raust be equal to six times the number of volumes in the 
file for the 5444; seven times the number of volumes for 
the 5445. 


Disk DTF Offsets (SDTOD) 


This macro instruction generates a list of equates used to 
label the fields in the post-open disk DTF. The labels 
generated are provided with the disk post-open DTF in 
Appendix B: Define the File Control! Blocks. The labels 
generated by the macro instruction are offsets from the 
beginning of the DTF and must be used as displacements 
from the DTF address when you access the DTF. 


The format of the $DTOD macro instruction is: 


| | $DTOD | | 


Input/Output Block for Disk ($1OBD) 


This macro instruction generates a disk input/output 

block (1OB) for use by the disk input/output supervisor. 

A 22-byte IOB is generated for 5444 disk devices, a 26- 
byte IOB is generated for 5445 disk devices. For a detailed 
description of the disk 1OB, see Appendix C: Disk Input/ 
Output Block. 


The format of the $1OBD macro instruction is: 


[DISK-5444/5445] [,CYL-number] 
[, SCTR-number) [,HEAD-number] 
[,NUM-number] [,BUFF-address] 
[,Q-number] [,ERREC-1OS/USER] 
[,LOG-Y/N] [,VER-Y/N] 

[ CHN-address] 


Disk-5444 or 5445 specifies whether the disk device being 
used is the IBM 5444 Disk Storage Drive Model 1 or the 
IBM 5445 Disk Storage. 


CYL-number indicates the beginning cylinder to be accessed. 
You can specify the cylinder by a decimal number (1-199) or 
or a hex number (X‘01’-X‘C7’) for the 5445, a decimal num- 
ber (4-202) or a hex number (X‘04'-X‘CA’) for the 5444, or 
a decimal number (1-166) or a hex number (X‘01’-X‘A6’) 


for the 3340. If this operand is not entered, X’FF’ is assumed. 


You must then insert the correct number into the |OB before 
performing the input/output operation. This can be done 
through the macro used to initiate the 1/O operation. 


SCTR-number specifies the first sector to be accessed. The 
number specified must be a decimal from 1 through 48 for 
the 5444 and 3340 disk drives or from 1 through 20 for the 
5445 disk drive. If this operand is not entered, X‘FF’ is 
assumed. You must then insert the correct number before 
performing the input/output operation. You can specify the 
sector through the $RDD and $WRTD macro instructions. 


HEAD-number is specified only for the 5445 disk storage 
drive. It specifies the head to be used with the cylinder 
and sector when an I/O operation is performed. The 
number specified may be decimal (0-19) or hexadecimal 
(X‘00’-X‘13'). If this operand is omitted, X‘FF’ is 
assumed and the value must be updated when the I/O 
operation is performed. 


NUM-number specifies the number of sectors used. You 
may specify the number in either decimal or hexadecimal 
form. If this operand is not entered, X‘00’ is assumed. 
You must then update this number in the |OB before 
performing the input/output operation. This can be done 
through the macro instruction used to issue the input/ 
output operation. 


BUFF-address is the address of the leftmost byte of your 
data area. If this operand is omitted, X‘'FFFF’ is assumed, 
and you must update the IOB before performing the 
input/output operation. 


Q-number specifies the drive on which the record is lo- 
cated. You may specify the disk drive alone (F1,R1,F2, 
R2,D1,D2), or you may specify the hexadecimal Q-code 
in the form O-X‘nn’, where nn is a valid hexadecimal Q- 
code. The valid O-codes are shown in Figure 15. If you 
specify only the disk drive, you must set the read/write 
bits (the last four bits of the Q-code) before you can per- 
form the |/O operation. This can be done through the 
$RDD or $WRTD macro instructions. : 


1/O 
Operation 


Control 


Q-Byte Setting (Hex) 


DRIVE 1 DRIVE 2 


5444 Removable Disk 


> 


Read 


NO 
99) 
NO 


Write 


oS) 
OO 
Ww 


Scan 


mn 
~ | Oo 


5444 Fixed Disk 


0 
08) 
0 


_ Control 


Read 


© 


Write 


uy) 


> 
oO] o 


Scan 


Figure 15. Q-Byte Hexadecimal Settings 


OQ 
ee) 


0 
C1 
C2 
C3 


Qalalo 
wolpl © 
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ERREC-IOS or USER indicates whether the input/output | 


supervisor is to handle error recovery. If you specify IOS, 
the supervisor handles error recovery and retries the opera- 
tion when errors occur. If you specify USER, the super- 
visor does not retry the operation and returns control to 
you. If this operand is not specified, |OS is assumed. 


LOG-Y or N indicates whether the !/O supervisor is to log 
errors that occur during the operation. If you specify 

Y (yes), error conditions are logged on the system pack. 
This information is used by IBM customer engineers. -N 
(no) indicates no logging is to be done for this IOB. If 
this operand is not entered, Y is assumed. 


VER-Y or N is used for output operations. Y (yes) indi- 
cates the written data should be verified; N (no) indicates 
it should not. If this operand is omitted, Y is assumed. 


CHN-address specifies the address of the leftmost byte of 
the next |OB for the operation if more than one IOB is 
required. 7 
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Input/Output Block Offsets ($1OED) 


This macro instruction generates equates to establish labels 
for the disk IOBs. These labels are offsets from the begin- 
ning of the IOB and are used as displacements from the 
beginning of the I|OB when you wish to refer to one of 

the fields. The labels generated by this macro instruction 
are given with the fields of the 1|OB in Appendix C: Disk 
Input/Output Block. 


The format of the $1O0ED macro instruction is: 


| | $IOED | | 


Construct a Disk Get Interface (SGETD) 


The $GETD macro instruction generates the interface 
needed to communicate with disk data management when 
a record is being read from a disk file. To use this macro 
instruction, construct a disk DTF for the file and use the 
$DTOD macro instruction to establish the offsets for the 
DTF. You must also provide the labels for the necessary 
data management routines through EXTRN statements in 
your programs. The names of the data management mod- 
ules and the functions of the modules are shown in Figure 
16. If you will need to use the data in register 2 at a later 
time, you should save the contents of that register before 
issuing the $GETD macro instruction. 


The code generated by this macro instruction gives con- 
trol to the data management routine; the routine com- 
pletes execution and returns control to the generated 
code. The generated code tests the completion codes 
returned by data management. 


The format of the $GETD macro instruction is: 


AC-code[,DTF-address} 

{,ERR-address] [,EOF-address] 
[,NRF-address] [,LSTV-address] 
[,NOKY-address] 


$GETD|$PUTD 


XS 


CANS SERN RE RS MS 


WS. ONS NSS MASK: NASR 


CXS YX WCNQN ALN RRR 


RES 


M 
M 
M 
M 
M 
M 
L 
L 
L 
L 
L 
L 
L 
L 
L 
L 
L 
L 
L 
L 
M 
M 
M 
M 
L 
L 
L 
L 
L 
L 
L 


sT rrss s88S85 


System Module 


$$CSOP 


$$CSOM 
$$CSIP 
$$CSIM 


$$CSOP 
$$CSOM 
$$CSUP 
$$CSUM 


$$DAID 
$$DAIB 
$$DAIT 
$$DAIM 


$$DAUD 
$$DAUB 
$$DAUT 
$$DAUM 


$$DAUD 
$$DAUB 
$$DAUT 
$$DAUM 


$SIOAD 
$SIOAM 
$$IOUT 
$$10UM 


SSIRIP 

$$IRAD 
$$1RAM 
$$IRBM 


$$SIRIM 

$$IRUP 
$SIRUA 
$$IRUM 


SSISIP 

$$ISAD 
$$ISAM 
$$ISBM 


$SISIL 

$SISIM 
$$ISUP 
$$ISUL 


$$ISUM 
$$SISUA 


5445 


$$CFOP 
$$CFOM 
$$CFIP 
$SCFIM 


$$CFOP 
$$CFOM 
$$CFUP 
$$CFUM 


$$DFID 
$$DFIB 
$$DFIT 
$$DFIM 


$$DFUD 
$$DFUB 
$$DFUT 
$$DFUM 


$$DFUD 
$$DFUB 
$$DFUT 
$$DFUM 


$$SIFAD 
$SIFAM 
$SIFUT 
$$IFUM 


$SSIGIP 

$$1GAD 
$$1GAM 
$$1GBM 


$$SIGIM 

$$1GUP 
$SSIGUA 
$$1GUM 


S$SIHIP 

$$IHAD 
$$IHAM 
$$1HBM 


S$SIHIL 

$SIHIM 
$$IHUP 
$$IHUL 


$$IHUM 
$$IHUA 


Access Method 


Consecutive Add 
Consecutive Add Multivolume 
Consecutive Get 

Consecutive Get MVF 


Consecutive Output 
Consecutive Output MVF 
Consecutive Update _ 
Consecutive Update MVF 


Direct Get 

Direct Get (Binary Keys) 
Direct Get (Binary Keys) MVF 
Direct Get MVF 


Direct Output 

Direct Output (Binary Keys) 
Direct Output (Binary Keys) MVF 
Direct Output MVF 


Direct Update 

Direct Update (Binary Keys) 
Direct Update (Binary Keys) MVF 
Direct Update MVF 


Indexed Add 
Indexed Add MVF 
Indexed Output 
Indexed Output MVF 


Indexed Random Input 

Indexed Random Add 

Indexed Random Add MVF 

tndexed Random Update & Add MVF 


Indexed Random Input MVF 
Indexed Random Update 
Indexed Random Update & Add 
Indexed Random Update MVF 


Indexed Sequential Input 

Indexed Sequential Add 

Indexed Sequential Add MVF 

Indexed Sequential Update & Add MVF 


Indexed Sequential Input Within Limits 
Indexed Sequential Input MVF 

Indexed Sequential Update 

Indexed Sequential Update Within Limits 


Indexed Sequential Update MVF 
Indexed Sequential Update & Add 


The Model 12 does not support multivolume or indexed disk files in the simulation area; thus AC (access) codes in these 


macros reflect these differences. 


Figure 16. Disk Data Management Modules 


Macro Instruction Statements 35 


AC-code specifies the appropriate access method. One of 
the codes from Figure 16 must be used. 


DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


ERR-address supplies the address in your program where 
control should be passed in the event of a permanent I/O 
error. If this operand is not specified, no permanent I/O 
error checking code is generated. 


EOF-address specifies the address in your program that 
receives control when the end of file is detected. You 
must not use this operand with random or direct access 
methods. 


NRF -address must be used only for random and direct 
access methods. It specifies the address in your program 
that is to receive control when a no-record-found condition 
occurs. 


LST V-address is used when processing a random, offline, 
multivolume file. This operand supplies the address in 

your program which receives control when the requested 
key is too high for the final volume in a multivolume file. 


NOK Y-address supplies the address in your program that 
is to receive control under either of the following condi- 
tions: 


@ The requested key is too low for the current volume 
when processing an indexed random offline multi- 
volume file. 


@ The requested key is too high for any volume when 
processing an indexed random online multivolume file. 


_ This operand is not used with other access methods. 
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Read From Disk (SRDD) 


This macro instruction generates an interface to the disk 
input/output supervisor that is to read from the disk 
device. When using this macro instruction, you must: 


e@ Provide an |OB and use the $10ED macro instruction 
to establish the offsets in the IOB. 


e Wait for the completion of the input operation. 


e Check for end of data when the record is received. 


If both reading and writing are to be performed (using the 
same 1OB) for a program, the bits of the Q-byte will be 
altered to cause an invalid operation. In this case, you must 
set off the bits of the O-byte for all but the first read (or 
write) operation in the program. 


If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 
the $RDD macro instruction. 

The format of the $RDD macro instruction is: 


1OB-address,CS-address, NSECT -number 
[ DISK-5444/5445] 


[Name] $RDD 


/OB-address provides the address of the leftmost byte of 
the 1OB which you created through your $10BD macro 
instruction. The label provided must be the same as the 
name specified on your $1O0BD macro instruction. 


CS-address is the address of the rightmost byte of the 
main storage area containing the disk cylinder/sector 
address of the area you want to read. The cylinder/sector 
address for use with the 5444 is a two-byte, hexadecimal 
number. The first byte specifies the cylinder; the second 
specifies the sector. For use with the 5445, a three-byte 
hexadecimal disk address is provided through this entry. 
The first byte specifies the cylinder; the second, the head 
number; the third, the sector. 


NSECT-number indicates the hexadecimal number of 
sectors, Minus one, to be read in this operation. 


DIS K-5444 or 5445 specifies whether the operation is on 
a 5444 disk drive or a 5445 disk drive. If this operand is 
omitted, 5444 is assumed. 


Construct a Disk Put Interface (SPUTD) 


The $PUTD macro instruction generates the interface 
needed to communicate with disk data management when 
putting a record to disk or updating a previously retrieved 
record. You must provide a DTF for the file and use the 
$DTOD macro instruction to establish the offsets in the 
DTF. You must also provide, through EXTRN statements 
in your program, the labels of the disk data management 
modules necessary to perform the output operation. (See 
Figure 16). If you will need to use the data in register 2 
at a later time, you should save the contents of that regis- 
ter before issuing the $PUTD macro instruction. 


The code generated by this macro instruction gives control 
to the data management routine; the routine completes 


execution and returns control to the generated code. Com-- 


pletion codes are tested and control is returned to your 
program. 


The data management used for direct output is really for 
direct update; therefore, you must use the update method 
_of processing. 


The format of the $PUTD macro instruction is: 


AC-code[,DTF-address] 
[,ERR-address] [,EOX-address] © 
[,DUP-address] [,SERR-address] 
[,KERR-address] [,UPD-Y/N] 
[,LSTV-address] [,NOKY-address] 
[, HKER-address] 


AC-code specifies the access method being used. One of 
the codes from Figure 16 must be used. 


DTF-address specifies the address of the DTF associated 
with this file. If this operand is not specified, the address 
is assumed to be in register 2. 


ERR -adadress is the address of the area in your program 
where control should be passed when a permanent I/O 
error occurs. If this operand is not specified, no permanent 
|/O error checking code is generated. 


EOX-address supplies the address in your program that is 
to receive control when an end of extent is reached during 


the operation. This operand is entered only when creating 
a consecutive or indexed file or when records are to be 


added to the file. 


DUP.-address provides the address in your program that is 
to receive control when an attempt to add a duplicate 
record has occurred. This operand is used only with an 


‘add access method. 


SERR-address is the address in your program where control 
is passed in the event of a sequence error while loading an 
indexed file. 


KERR-address specifies the address of your routine to be 
called when an attempt has been made to update a record 
in an indexed file and the attempt would destroy the 
record key. | 


UPD-Y or N indicates whether an update is to be per- 
formed. If this operand is not entered, N (no) is assumed. 


LSTV-address specifies the address in your program that 
receives control when a requested Key is too high for 
the last specified volume. This operand is used only 
when processing an indexed, random, offline, multi- 
volume file. 


NOK Y-address supplies the address in your program that 
is to receive control under either of the following condi- 
tions: 


@ The requested key is too low for the current volume 
when processing an indexed, random, offline, multi- 
volume file. 


@ The requested key is too high for any volume when 
processing an indexed random online multivolume file. 


This operand is not used with other access methods. 


HKER-address specifies the address in your program that 
is to receive control when an indexed sequential add multi- 
volume is attempted and the requested key is higher than 
any key presently in the file, but lower than the highest 
permissible key. 
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Write to Disk (SWRTD) 


This macro instruction generates an interface to the disk 
input/output supervisor needed to write recG ds to disk. 
When you use this macro instruction, you must: 


@ Provide an IOB, and use the $1OED macro instruction 
to establish the offsets in the IOB. 


@ Wait for the completion of the output operation. 


If both reading and writing are to be performed (using the 
same |OB) for a program, the bits of the Q-byte will be 
altered to cause an invalid operation. In this case, you 
must set off the bits of the Q-byte for all but the first 
read (or write) operation in the program. 


If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 
the macro instruction. 


The format of the $WRTD macro instruction is: 


[Name] $WRTD |OB-address,CS-address, NSECT-number 


[,DISK-5444/5445] 


/OB-address provides the address of the disk 1OB for this 
operation. The address is the name specified on the 
related $1OBD macro instruction. 


CS-address is the address of the rightmost byte of the 
main storage area containing the disk cylinder/sector 
address of the area to which you want to write. The 
cylinder/sector address for use with the 5444 is a two- 
byte hexadecimal number. The first byte specifies the 
cylinder; the second specifies the sector. For use with 
the 5445, a three-byte hexadecimal disk address is pro- 
vided through this entry. The first byte specifies the 
cylinder; the second, the head number; the third, the 
sector. | 


NSECT-number specifies the number of disk sectors, 
minus one, to be written. 


DIS K-5444 or 5445 specifies whether the operation is on 
a 5444 disk drive or a 5445 disk drive. If this operand is 
omitted, 5444 is assumed. 
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Wait for Disk |OS Completion (SWAIT) 


This macro instruction is used with the $RDD and 
$WRTD macro instructions. It generates the code which 
allows you to wait for completion of the disk 1OS opera- 
tion. You provide the label of the associated I|OB (whose 
offsets are established through the $1OED macro instruc- 
tion) and an address to receive control in the event of an 
error. If you will need to use the data in register 1 at a 
later time; you should save the contents of that register 
before issuing the $WAIT macro instruction. 


The format of the $WAIT macro instruction is: 


[Name] $SWAIT [t\OB-label] [,ERR-address] 


/OB-label is the name assigned to the [OB in the $IOBD 
macro instruction. This same I|OB must have previously 
been specified in either a $RDD or $WRTD macro instruc- 


tion. If this operand is not entered, the address is assumed 


to be in register 1. 


ERR-address specifies the address of the routine in your 
program that handles errors detected in the operation. If 
this operand is not entered, no error checking is performed. 


Tape Device Support 


This section describes the macro instructions that support 
the IBM 3410/3411 Magnetic Tape Subsystem. The follow- 
ing functions are provided: 


e Build a pre-open DTF for tape and assign its offsets. 


e Build the interfaces required to read input records from 
a tape device via a get or a read. 


e@ Build the interfaces required to write output records to 
a tape device via a put or a write. 


@ Build the interface required to issue tape control 
commands. 


@ Wait for completion of read, write, or tape control 
operations. 


The tape DTFs provide information to the tape data manage- 
ment routines that perform the input/output operations. 
These operations are provided through the tape support 
macro instructions. 


Define the File for Tape (SDTFT) 


The DTF provides information needed to allocate and open 
a tape device. This macro instruction generates the code 
that builds the tape DTF. See Appendix B: Define the 
File Control Blocks for a description of the pre-open and 
post-open DTFs. 


The format of the $DTFT macro instruction is: 


NAME-filename,!O-address, 
AC-IN/OUT,BLKL-number, 
RECL-number [,UP-mask] 
[,CHN-address] [,BASIC-Y/N] 
[, MODE-LOCATE/MOVE] 


[, MBUFF-Y/N] [,RCAD-address] 
[,RECFM-code] [,L}OA-number] 
[,SPAN-Y/N] [,CODE-A/E] 

[,OSET-B/number] [,END-code] 


NAME-filename is a required operand specifying the name 

of the tape file. The filename can be up to eight characters 
in length and must be the same as the name on the // FILE 
statement. 


/O-address specifies the address of the leftmost byte of the 
main storage area used to contain all buffers and l|OBs. This 
operand is required. The length of the area specified by 
this address is specified in the LIOA operand. 


Note: \f basic data management routines are used to 
process the file, this operand should point to a 22-byte 
area to contain the tape IOB. 


AC-IN or OUT specifies the type of file. IN specifies an 
input file; OUT, an output file. This operand is required. 


BLKL-number is a required operand that specifies the 
decimal block length for the file. The minimum block 
length allowed is 18 bytes. If a shorter length is specified, 
18 is assumed. For files with fixed-length records, the 
block length must be a multiple of the record length; for 
files with variable-length records, the block length must 
equal, the length of the longest record plus eight. 


Note: \f basic tape data management is used, the block 
length in the DTF (STDBKL) must be updated after the 
file is opened and before any read or write operation is 
performed. The field must also be updated before any sub- 
sequent read or write if the length used is different than 
the previous read or write. 
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RECL-number is a decimal value specifying the length of a 
logical record in the file. If variable-length records are used 
for the file, the record length specified must be equal to the 
longest record plus four. The minimum record length when 
variable-length records are used is four, which results in 
zero-length records. The minimum record length for files 
using fixed-length records is 18. This operand is required. 


UP-mask specifies the settings of the external (// SWITCH 
statement) indicators used for conditionally opening files. 
The code must be specified as eight binary bits. For 
example, to set on bits 0, 3, 5 and 7, you would enter 
UP-10010101. If this operand is not entered, zeros are 
assumed. 


CHWN-address indicates the address of the next DTF in the 
chain of DTFs. If there is no DTF chain, the operand is 
omitted and X‘FFFF’ is assumed. 


BASIC-Y or N specifies whether this DTF uses the basic 
access method. If this operand is not entered, N (no) is 
assumed. 


' Note 1: BASIC-Y must be specified if any of the following 
macro instructions are used to process the file: $RDT, 
SWRTT, $CTLT or $WTT. 


Note 2: \f you process ASCII files using the basic access 
method, you must translate the characters in your program. 


Note 3: Multivolume files are supported with the basic 
access method; the EXTRN that is used for this method 
must be for $$BTMM. $$BTTM and $$BTAM cannot be 
used in the same program. $$BTMM supports both single 
and multivolume files. 


Note 4: Deferred open is not allowed with the basic 
access method. 


MODE-LOCATE or MOVE indicates whether the locate 
mode or move mode is used. If this operand is not speci- 
fied, MOVE is assumed. When locate mode is specified, 
the record address (RCAD-address) is set to the address 
of the record in the buffer. When move mode is used, 
records are moved from the buffer to the location speci- 
fied by the record address. 


Locate mode is valid only for input files. 
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MBUFF-Y or N indicates whether more than one buffer is 
used. If this operand is not specified, N (no) is assumed. 
The number of buffers is determined by the length of the 
I/O area, specified by the LIOA operand. 


RCAD-address specifies the symbolic record area address 
when move mode is used. If this operand is not specified, 
‘0000’ is assumed and the address must be supplied when 
the operation is requested. 


Note: When basic tape data management routines are used 
to process the file, this operand must point to an area of at 
least 80 bytes for use by the open routine. After the file 

is opened, another area can be used as the buffer. To do 
this, you must update the buffer address at location 
$TDWKB in the tape DTF. 


RECFM-code specifies the record format used for the file. 
The codes and their meanings are: 


Code Record Format 

F Fixed, EBCDIC or ASCII 

FB Fixed blocked, EBCDIC or ASCII 
V Variable, EBCDIC 

VB Variable blocked, EBCDIC 

D Variable, ASCII 

DB Variable blocked, ASCII 


If this operand is not specified, F is assumed. 


L/!OA-number is the total decimal length of the I/O area. 
If multiple buffers are used, the area must be large enough 
to contain the IOBs and buffers for the number of buffers 
used. The following formula can be used to determine the 
length of the buffer area: 


LIOA = (22 + block length) (number of buffers). 


The minimum length of 102 mytes is assumed if this 
operand is not specified. 


SPAN-Y or N specifies whether spanned records are used. 
If spanned records are used, BASIC-Y must also be 
specified. If this operand is omitted, N (no) is assumed. 
Specifying SPAN-Y causes the spanned record bit in the - 
tape label to be set on. When you use SPAN-Y, you must 
span the records from block to block. 


CODE-A or E specifies whether the file is an EBCDIC file 
or ASCII file. If the file is an EBCDIC file, specify CODE- 
E. If the file is an ASCII file or can be either ASCII or 
EBCDIC, specify CODE-A. If this operand is not entered, 
E is assumed. 


Note: \f CODE-A is specified in $DTFT, the CODE oper- 
and in the $GETT or $PUTT macro instruction must also 
be A. If CODE-E is specified in $DTFT, the CODE oper- 
and in the $GETT or $PUTT macro instruction can be 
either A or E. 


OSET-B or number specifies the buffer offset of an ASCII 
block. B indicates that the first four bytes of the block 
contain the decimal block length and no buffer offset is 
present. B is valid only when RECFM-D or RECFM-DB is 
also specified. Only OSET-B or OSET-00 are valid for out- 
put files. OSET-number specifies, in decimal, the length of 
the buffer offset for the ASCII block. This buffer offset is 
skipped over when the record is supplied to your program. 
The maximum valid specification is OSET-99. If this oper- 
and is not specified, zero is assumed. 


END-code specifies the tape control actions to be taken 
when the file is closed. The valid codes and their meanings 
are: 


Code Action 
Rewind the tape 


Rewind and unload the tape 
No action taken 


REWIND 
UNLOAD 
LEAVE 


If this operand is not entered, REWIND is assumed. 


Tape DTF Offsets (SDTOT) 


This macro instruction generates a list of equates used to 
label the fields in the post-open tape DTF. The labels 
created are provided with the tape post-open DTF in 
Appendix B: Define The File Control Blocks. The labels 
generated by the macro instruction are offsets from the 
beginning of the DTF and must be used as displacements 
from the DTF address when you access the DTF. 


The format of the macro instruction is: 


| | $DTOT | | 


Construct a Tape Get Interface (SGETT) 


The $GETT macro instruction generates the interface 
required to communicate with tape data management when 
a record is being read from a tape file. To use this instruc- 
tion, you must construct a tape DTF for the file and use 
the $DTOT macro instruction to establish the offsets in the 
DTF. If you will need to use the data in register 2 at a 
later time, you should save the contents of that register 
before issuing the $GETT macro instruction. You must 
also provide the labels for the necessary data management 
routines through EXTRN statements in your program. The 
names and functions of the data management routines are 
shown in Figure 17. 


Module | 
7 ° P 
Naina Type of File Being Processed 


$$CSIT 
$$CSOT 
$$CSIA 
$$CSOA 
$$CSTI 
$$CSTO 
$$CSAI 
$$CSAO 


EBCDIC fixed input 


EBCDIC fixed output 


EBCDIC or ASCII fixed input 


EBCDIC or ASCII fixed output 


EBCDIC fixed or variable input 


EBCDIC fixed or variable output 


EBCDIC or ASCII fixed or variable input 


EBCDIC or ASCII fixed or variable output 


Figure 17. Tape Data Management Modules 
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The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. If the 
ERR or EOF operand is specified, the generated code tests 
the completion code returned by data management and 
branches to your routine. If reading variable length records, 
tape data management returns the length of the record at 
label STDCRL in the DTF. 


The format of the $GETT macro instruction is: 


[DTF-address] [,CODE-A/E] 
[,RECFM-EF/V] [,ERR-address] 


{ EOF-address] 


DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


CODE-A or E specifies whether any ASCII files are used in 
this program. This determines whether the data manage- 
ment modules used to process the files must be capable of 
processing both EBCDIC and ASCII files. A indicates 
ASCII files are used in your program; E indicates only 
EBCDIC files are used. If this operand is omitted, E is 
assumed. 


Note: This operand determines the data management 
module that will process the file. One set of data manage- 
ment modules processes only EBCDIC files, another set 
processes both EBCDIC and ASCII files. If you have only 
EBCDIC files in your program, less main storage is required 
if you specify CODE-E or omit this operand. If you have 
both types of files in your program, less main storage is 
required if you specify CODE-A, even though you are read- 
ing an EBCDIC file. 


The entry for this operand must correspond with the data 


management module name provided in the EXTRN in 
your program. 


RECFM-F or V specifies whether the record to be read is 


fixed-length or variable-length. If this operand is not speci- © 


_ fied, F is assumed. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled can- 
cel completion code. 
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EOF-address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
operand is not supplied, no code is generated to check for 
the end-of-file condition. 


Note: \f ERR or EOF addresses are not specified, you 
should check the return code in your program to deter- 
mine the outcome of the operation. 


Read from Tape ($RDT) 


This macro instruction generates an interface to basic tape 
data management to read from a tape device. When using 
this macro instruction, you must: 


e@ Provide a tape DTF and use $DTOT to establish the 
offsets in the DTF. 


@ Wait for completion of the input operation and check 
for end-of-file by using the $WTT macro instruction. 


@ Provide EXTRN statements in your program for the 
basic tape data management module ($$BTAM or 
$$BTMM) and for the entry point to the read routine in 
that module (DMBTRW). | 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $RDT macro instruction. The generated code for this 

macro instruction uses register 2. 


The code generated by this macro instruction branches to 
basic tape data management to begin the read operation. 


The format of the $RDT macro instruction is: 


[Name] $RDT [DTF-address] 


[ DIRECT-EORW/BACK] | 


DTF-address specifies the address of the leftmost byte of 
the DTF for the file. If this operand is not entered, the 
address is assumed to be in register 2. 


DIRECT-FORW or BACK specifies the direction of the 
read. If this operand is not entered, forward (FORW) is 
assumed. 


Construct a Tape Put Interface (PUTT) 


This macro instruction generates the interface needed to 
communicate with tape data management when writing a 
record to tape. You must provide a DTF for the file and 
use the $DTOT macro instruction to establish the offsets 
in the DTF. You must also provide, through EXTRN 
statements in your program, the labels of the tape data 
management modules necessary to perform the output 
operation (see Figure 17). 


lf you will need to use the data in register 2 at a later time, 


_ you should save the contents of that register before issuing 


the $PUTT macro instruction. 


The code generated by this macro instruction gives control 


to the data management routine. The routine completes 
execution and returns control to the generated code. If 
the ERR operand is specified, the generated code checks 
the completion code for errors and branches to your error 
routine if errors occurred. 


The format of the PUTT macro instruction is: 


[DTF-address] [,CODE-A/E] 
[,RECFM-F/V] [,ERR-address] 


[Name] $PUTT 


DTF-address specifies the address of the leftmost byte of 
the DTF for the file. If this operand is not specified, the 
address is assumed to be in register 2. 
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CODE-A or E specifies whether any ASCII files are used by 
your program. This determines whether the data manage- 
ment modules used to process the file must be capable of 
processing both EBCDIC and ASCII files. A indicates 
ASCII files are used in your program, E indicates only 
EBCDIC files are used. If this operand is omitted, E is 
assumed. 


Note: This operand determines the data management 
module that will be used to process the file being defined. 
One set of data management modules processes only 
EBCDIC files, another set processes both EBCDIC and 
ASCII files. If you ‘have only EBCDIC files in your pro- 
gram, less main storage is required if you specify CODE-E 
or omit this operand. If you have both types of files in 
your program, less main storage is required if you specify 
CODE-A, even though you are defining an EBCDIC file. 
The entry for this operand must correspond with the data 
management module name in the EXTRN in your program. 


RECFM-F or V specifies whether the record is fixed-length 
or variable-length. If this operand is not specified, F is 
assumed. 


ERR-address specifies the address in your program where 
control should be passed if a permanent !/O error occurs. 

If this operand is not entered, no permanent I/O error 
checking code is generated and you should check the return 
code in your program to determine the outcome of the 
operation. 
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Write to Tape (SWRTT) 


This macro instruction generates the interface to basic tape 
data management needed to write records to tape. When 
you use this macro instruction, you must: 


@ Provide a DTF for the file and use the $DTOT macro 
instruction to establish the offsets in the DTF. 


e Wait for the completion of the |/O operation by using 
the $WTT macro instruction. 


@ Provide EXTRN statements in your program for the 
basic tape data management module ($$BTAM or 
$$BTMM) and for the entry point to the write routine 
in that module (DMBTRW). 


if you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $WRT macro instruction, because the generated code 
for that macro instruction uses register 2. 


The code generated by this macro instruction branches to 
basic tape data management to start the operation. 


The format of the $WRT macro instruction is: 


[Name] - SWRTT [DT F-address] 


DTF-adadress is the address of the leftmost byte of the DTF 
for the file. If this operand is not specified, the address of 
the DTF is assumed to be in register 2. 


Control Command for Tape ($CTLT) 


This macro instruction generates the interface to basic tape 
data management to issue control commands to the tape 
device. It is not used to get records from or put records 
out ona tape file. To use this macro instruction, you 
must: 


@ Provide a DTF for the file on the tape device and use 
the $DTOT macro instruction to establish the offsets in 
the DTF. | 


e Wait for completion of the operation by issuing the 
$WTT macro instruction. 


@ Provide EXTRN statements in your program for the 
basic tape data management module ($$BTAM or 
$$BTMM) and for the entry point to the control routine 
in that module (DMBTPS). 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $CTLT macro instruction. 


The code generated by this macro instruction branches to 
the basic tape data management to initiate the operation. 


The format of the macro instruction is: 


[Name] $CTLT [DTF-address] [,OPC-code] 


DTF-address specifies the address of the leftmost byte of 

the DTF for the file on the tape device. If this operand is 
not specified, the address of the DTF is assumed to be in 

register 2. 


OPC-code specifies the control operation to be performed. 
The valid codes and their meanings are: 


Code Operation 

FSF Forward space file 

FSB Forward space block 
BSF Backspace file 

BSB Backspace block 

REW Rewind tape 

RUN Rewind and unload tape 
WTM Write tape mark 


If this operand is not specified, rewind tape, REW, is 
assumed. 


Wait For Tape 1/0 Completion (SWTT) 


This macro instruction is used with the $RDT, $WRTT, 
and $CTLT macro instructions. It generates the linkage 

to basic tape data management in order for the tape data 
management to wait for the completion of operations that 
have been initiated. You must provide the address of the 
tape DTF for the file and use the $DTOT macro instruction 
to establish the offsets for that DTF. You must also pro- 
vide EXTRN statements in your program for the basic 

tape data management module ($$BTAM or $$BTMM) and 
for the entry point in the wait routine in the module 
(DMBTWT). You may also provide addresses where control 
is to be returned in the event of a permanent I/O error, 
end-of-file condition, or end-of-tape condition. 


If you will need to use the data in register 2 at a later 
time, you should save the contents of that register before 
issuing the $WTT macro instruction. 


The generated code from this macro instruction checks the 
completion code in the DTF to determine the outcome of 
the operation. When an abnormal completion is detected. 
control is passed to the appropriate address in your pro- 
gram, if you have specified ERR, EOJ, or EOT, or to the ~ 
next instruction in your program. 


The format of the $WTT macro instruction is: 


[Name] SWTT [DTF-address] [,ERR-address] 


[,EOF-address] [,EOT-address] 


DTF-address specifies the address of the leftmost byte in 
the DTF for the file. If this operand is omitted, the 
address of the DTF is assumed to be in register 2. 


ERR-address is the address of the routine in your program 
that receives control when a controlled cancel is indicated 
in the completion code. If this operand is not entered, the 
controlled cancel is ignored and control returns to the 
next instruction in your program. 


EOF-address specifies the address of your routine that 
receives control when end-of-file occurs. If this operand is 
omitted, the end-of-file condition is ignored and control 
returns to the next instruction in your program. 


EOT-address is the address of the routine in your program 
that receives control when end-of-tape is detected. If this 
operand is not specified, the condition is ignored and con- 
trol returns to the next instruction in your program. 


Note: If ERR, EOF, or EOT addresses are not specified, 


you should check the return code in your program to 
determine the outcome of the operation. 
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| 3741 Support Define the File for 3741 (SDTFK) 


This section describes the macro instructions that support This DTF provides information needed to allocate, open, 
the IBM 3741 Data Station/Programmable Work Station. and access a file on the 3741. This macro instruction gener- 
The following functions are provided through the use of ates the code that builds the 3741 DTF. 


these macro instructions: 
The format of the $DTFK macro instruction is: 
@ Build a preopen DTF and assign its offsets. 


NAME-filename,RECL-number, 
1O-address [,AC-I/O] 


@ Build the interface required to read input records from 
[,RCAD-address] [,BUFNO-1/2] 


the 3741 via a get. [,CHN-address] [,UP-mask] 


@ Build the interface required to write output records to a 
3741 via a put. NAME-filename is a required operand specifying the name 


of the 3741 file. The name may not exceed eight characters 


The 3741 DTFs provide information to the data manage- in length. 


ment routines that perform the input/output operations. 
These operations are provided through the 3741 macro 
instructions. 


RECL-number is a decimal value specifying the length of a 
logical record. The decimal value may be from 1 to 128. 


/O-address specifies the address of the leftmost byte of the 
main storage area that is used to contain all buffers and 
lOBs. The length of the area specified by this address must 
be the record length plus 26 times the BUFNO. 


AC-//O specifies the type of DTF, input or output. If the 
operand is not entered, an input DTF is assumed. 


RCAD-address specifies the address of the leftmost byte of 
the logical record. If this operand is not entered, X‘FFFF’ 
is assumed. 


BUFNO-7 or 2 allows you to use one or two buffers. If this 
operand is omitted, one buffer is assunred. 


CHN-address indicates the address of the next DTF in the 
chain of DTFs. If there is no DTF chain, the operand is 
omitted and X‘FFFF’ is assumed. 


UP-mask specifies the settings of the external (// SWITCH 
statement) indicators used for conditionally opening files. 
The switch statement code must be specified as eight binary 
bits. For example, to set on bits 0, 3, 5, and 7, you would 
enter UP-10010101. If the switch statement operand is 

not entered, zeroes are assumed. | 
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Construct a 3741 GET Interface (S$GETK) 


When a record is being read from a 3741 file, the $GETK 
macro instruction allows the 3741 data management to 
communicate with the 3741 file. To use this instruction, 
you must construct a 3741 DTF for the file and use the 
$DTOD macro instruction to establish the offsets in the 
DTF. You must also provide an EXTRN statement with 
the label $$CPIP to use this macro. If you need to use the 
data in register 2 at a later time, you should save the con- 
tents of that register before issuing the $GETK macro 
instruction. 


The code generated by the $GETK macro instruction gives 
control to the data management routine; the routine com- 


pletes execution and returns control to the generated code. 


The format of the $GETK macro instruction is: 


[DT F-address] [,ERR-address] 
,EOF-address 


DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


ERR-address \f the controlled cancel option is taken in 
response to a permanent I/O error, the ERR-address sup- 
plies the address in your program to which control is passed. 
If this operand is omitted, no code is generated to check for 
the controlled cancel completion code. 


EOF -address specifies the address in your program to 
which control is passed when the end-of-file is detected. 
This operand must be specified. 


Construct a 3741 PUT Interface (SPUTK) 


When writing a record to the 3741, the $PUTK macro 
instruction allows the 3741 data management to communi- 
cate with the 3741 file. You must provide a DTF for the 
file and use the $DTOD macro instruction to establish the 
offsets in the DTF. You must also provide an EXTRN with 
the label $$CPOP to use this macro instruction. If you will 
need to use the data in register 2 at a later time, you should 
save the contents of that register before issuing the $PUTK 
macro instruction. The routine completes execution and 
returns control to the generated code. 


The format of the $PUTK macro instruction is: 


[Name] $PUTK [DT F-address] [,ERR-address] 


DTF-address specifies the address of the leftmost byte of 
the DTF for the file. If this operand is not specified, the 
address is assumed to be in register 2. 


ERR-address \f the controlled cancel option is taken in 
response to a permanent I/O error the ERR-address supplies 
the address in your program to which control is passed. If 
this operand is omitted, no code is generated to check for 
the controlled cancel completion code. 
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| CPU Commands 


Command CPU—Generate the CCP Assembler Instruction 
(S$CCP) 


The format of the $CCP macro instruction is: 


[Name] $CCP OBYTE-hex,RBYTE-hex 


OBYTE-hex is a required operand specifying the Q-code 
for the CCP instruction. 


RBYTE-hex is a required operand specifying the R-code for 
the CCP instruction. | 


Note: For acomplete description of the codes for the 
Q-byte and the R-byte that can be entered in the operands, 
see /BM System/3 Models 8, 10, 12, and 15 Components 
Reference Manual, GA21-9236. 

Load CPU—Generate the LCP Assembler Instruction ($LCP) 


The format of the $LCP macro instruction is: 


OBYTE-hex[,ADDR-address] 
[,REG-1/2] [,DISP-hex] 


[Name] $LCP 


OBYTE-hex is a required operand specifying the O-code 
for the LCP instruction. 


ADDR-address specifies the address of the data. This 
operand is required unless REG and DISP operands are 
specified. 


REG-1/2 specifies the base register for the displacement of 
the data. This operand is required unless ADDR operand 
is specified. 


DI/SP-hex specifies the displacement of the data from the 
address pointed to by the base register. This operand is 
required unless ADDR operand is specified. 


Note: For acomplete description of the codes for the O-byte 
that can be entered in the operand, see /BM System/3 Models 
&, 10, 12, and 15 Components Reference Manual, 
GA21-9236. 
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| Store CPU—Generate the SCP Assembler Instruction ($SCP) 


The format of the $SCP macro instruction is: 


OBYTE-hex[,ADDR-address] 


[,REG-1/2] [,DISP-hex] 


? 
QBYTE-hex is a required operand specifying the Q-code 


for the SCP instruction. 


ADDR-address specifies the address of the data. This 
operand is required unless REG and DISP operands are 
specified. 7 


REG-1/2 specifies the base register for the displacement 
of the data. This operand is required unless ADDR operand 
is specified. 


DISP-hex specifies the displacement of the data from the 
address pointed to by the base register. This operand is 
required unless ADDR operand is specified. 


Note: For acomplete description of the codes for the 
Q-byte that can be entered in the operand, see /BM 
System/3 Models 8, 10, 12, and 15 Components Reference 
Manual, GA21-9236. : 


OCL FOR MACRO PROCESSOR 


OCL statements used to load and run the macro processor 
can be entered through the system input device or can be — 
called from the procedure library. The OCL statements 
necessary to load and run the macro processor are shown 
in Figure 18. The COMPILE statement shown in Figure 18 
is necessary only when input is in a source library. 


SAMPLE PROGRAM 


This sample program uses the macro processor and the 
IBM System/3 Basic Assembler Program, program number 
5702-AS1. The coding shown in Figure 19 produces an 
object program. To use the program, you must link edit 
the object program and execute it. The macro processor 
can be used with any valid assembler on the IBM System/3 
Model 10 Disk System and is not limited to use with the 
program product 5702-AS1. 


Purpose of the Sample Program 


The sample program in Figure 19 is used to print input 
records entered from the system input device. It reads 
data records from the system input device and prints them 
ona line printer. Each printed line reproduces one input 
record. 
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Chapter 3. OCL and Sample Program 


Termination of the Sample Program 
The sample program terminates in one of two ways: 


1. After successful completion of the program, EJ is 
displayed on the console display unit. 


2. When an error occurs during processing, one of the 
following halts is displayed on the console display 
unit: 

A1—if an error is returned from the sysin routine. 

A2—if an error is returned from the printer routine. 
You respond to these halts by pressing the start key 
(or the halt/reset key on systems with the dual pro- 


gramming feature). EJ is then displayed on the 
console display unit. 
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Figure 18. OCL Statements for Using the Macro Processor 
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Figure 19 (Part 3 of 4). Sample Program 
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Figure 19 (Part 4 of 4). Sample Program 
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OCL and Sample Program 


Macro Instructions Used in the Sample Program 


Eight macro instructions are used in this sample program. 
The macro instructions and their functions are: 


Macro Instruction Function 

$S$ALOC Allocates the printer file to this 
program 

SOPEN Opens the file after allocation 

$SVC Reads input records from the 
system input device 

$GPU Prints output records on the 
printer 

$CLOS Closes the output file 

$EOJ Calls the end-of-job routine 

$DTFU Constructs the DTF for the 

| printer 
$DTOU Establishes the offsets for the DTF 
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Appendix A. Error Information 


Any errors made in coding macro instructions are flagged 
in the $SOURCE file. When an error is found in a macro Error Description 
instruction, an error code and an error message are placed 


; : : : , ‘ A keyword response has resulted in an invalid 
immediately following the macro instruction in the 


decimal digit or a boundary exceeded condi- 


$SOURCE file. The error code and message are then tion. (See note) 
printed on your assembly listing when the source program 
is assembled. An error in continuation exists in this macro in- 
struction. Nonblank characters were found in 
Figure 20 shows the error codes that may be caused by columns 1-13 of the continued line. All remain- 
errors in macro instructions. Other error codes may be ing lines of this macro instruction will be flagged 


with the error code ‘OC’. 
generated by the macro processor and are caused by errors 


in the macro definitions. These error codes are explained A keyword response resulted in a character string 
| in Appendix B in /BM System/3 Models 4, 6, 8, and 10 that exceeds the maximum length. (See note) 
System Control Program Logic Manual, SY21-0502. 


An error in continuation exists in the previous 
macro instruction. Column 72 is blank. All 
remaining lines of this macro instruction will be 
flagged with the error code ‘OC’. 


A delimiter is missing or invalid in the operand 
of the previous macro instruction. 


A keyword in the macro instruction being 


processed is not valid. 
& An invalid parameter has been found in one of 


the operands of the previous macro instruction. 


The macro instruction being processed contains 
a mnemonic operation code not contained in the 
source library of the program pack. 


The mnemonic operation code of the previous 
macro instruction is invalid. (See codes ‘CE’ and 
‘IC’ for a possible cause for this error code.) 


A keyword response has resulted in an invalid 
substring term. (See note) 


A keyword response has resulted in a substring 
syntax error. (See note) 


The variable symbol table is full. Recode your 
program using fewer macro instructions. 


Note: These errors may be the result of any macro instruction 
or combination of macro instructions that precede the error 
code. 


Figure 20. Macro Instruction Error Codes 
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GS*1 Halt SYSTEM HALTS AND THE MODULES THAT CAN 
ISSUE THEM 

The maintenance personnel can locate the 2-byte save area 

at the label AERSAV within $SGENB. See Figure B-14. Figure B-16 is provided to help determine which modules 

issue which halts. The figure contains a list of halts, the 

modules that initiate the halts listed, and a brief description 

of the reason for the halt being issued. The halts listed are 


cussed in this manual. 


eee An invalid completion 
Generation, code was received a 
Phase One from the SWA Read/ Note: The halts shown are converted by the Model 6 Halt/ 
Write routine. Syslog Transient ($$STOK) to display the Model 6 halt. 
See Part 6. Transients and Scheduler Support for a descrip- 
The // END state- tion of SSSTOK. 


ment is missing 


from the procedure 
on the distribution 
disk cartridge. 


Figure B- 14, Halt Codes for System Generation—Phase One 
fee ~ ($SGENB) GS’1 Halt . 


Macro Processing Error Messages 


If an error occurs during macro processing, a 2-byte 
error code and message is written into $SOURCE: 


ERROR *** cc *** PROCESSING ABOVE MACRO 
code 


A description of Macro Processor error codes is con- 
tained in Figure B-15. 
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Error Code Error Description 

Al An AGO or AGOB record has an invalid sequence symbol. 

AT A variable symbol table entry has an invalid attribute. 

BE A value compared in the operand of an AIF or AIFB record is more 
than 50 bytes long or has an invalid format (only symbolic parameters, 
set symbols, character strings, count functions, and type attributes are 
valid for comparison). 

A model record is more than 71 bytes long. 

Bl A position in a binary self-defining term is other than O or 1. 

BX Arithmetic term exceeds bounds of — 8,388,608 to + 8,388,607. 
Value of symbolic parameter or decimal self-defining 
term exceeds maximum value of 65,535. 

CE A macro instruction continuation statement has a non-blank entry 
in positions 1-13. 

Cl The count function is being used with other than symbolic parameters. 

CL A character expression length is greater than 50 bytes. 

E| An invalid operand or operator is used in an arithmetic expression. 
Valid operands are binary, character decimal, and hexadecimal self- 
defining terms; variable symbols; and count functions. Valid operators 
are addition (+), subtraction (-), multiplication (*), and division (/). 

EM A MEND record was found immediately following a TABLE record. 

ER Consecutive operators have been detected within an arithmetic expression. 

ET An arithmetic expression has been ended with an operator. 

HI A hexadecimal self-defining term contains an invalid hexadecimal digit. 

IA An error has been detected in the format of an AIF or AIFB record. 

IC The format of a macro instruction is for a continuation record to follow 
but continuation is not indicated. 

ID An invalid delimiter occurred following a keyword parameter ona 
macro instruction. 

IG A format error occurred in an operand of a GBLA, GBLB, GBLC, 
LCLA, LCLB, or LCLC record. 

IK An invalid keyword was found on a macro instruction. 

IM A sequence symbol is missing or misspelled. 

IP A prototype record has one of the following: 


@® Format error in an operand field 
@ Invalid entry in a name field 
@® Operation field name incorrect 


Figure B-15 (Part 1 of 3). Error Codes for Macro Processor 


Routine. 
S$MPMN3 
SMPATH 


SMPSB1 


$MPSUB 
$MPATH 


S$MPATH 


$MPCDX 


$MPXDV 


$MPATH, $MPSB1 


$MPCEX 


S$MPATH 


$MPMN2 
$MPATH 
$MPATH 
$MPATH 
$SMPAIF 


$MPOPR 
$MPOPR 
$MPGBL 
$MPOPR 


$MPRED 


$MPOPR 
$MPROT 
$MPSTM 
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Error Code Error Description Routine 


+S IR An invalid response to a keyword parameter was found on a $S$MPOPR 
macro instruction. 


Is The length of the sequence symbol on an AGO or AGOB record $MPAGO 
was not less than 6. 
An invalid variable symbol was found. $MPGSY 
IT An error has been encountered in the placement of control records $MPTBL 


prior to the TEXT record within a macro definition. 


1U A set symbol identified on a global or local record is also identified S$MPVST 
on a prototype or TABLE record within the same macro definition. 


IV An invalid value exists on the record being processed: $MPCSB, $MPNCB 
@ Null value when not permitted 
@ Value exceeds 50 bytes when decoded 


@® Value exceeds the limits of the record on which it appears 


LP Improper placement of left parenthesis or more than 3 levels of $MPATH 
nested parenthesis within an arithmetic expression. 


MM The macro definition records are not in the expected sequence. $MPMN3 
MN Invalid format on an MNOTE record. SMPNTT 
MS One of the fixed format fields of a model record has exceeded its $MPMST 
defined limits. An entry in field 1 must begin in position 1. 
& ND A TABDF record does not follow a TABLE record. $MPMN2 
NE No operator exists for the remaining operand in final step of $SMPATH 


arithmetic expression evaluation. 


NF The macro definition was not found in source library of program $MPMN1 
or system pack. 


NM An error has been encountered in the placement of control records SMPSTM 
following the text record within a macro definition 


NO Consecutive operands have been detected within an arithmetic expression. $MPATH 

NP An invalid combination of operators was specified in an arithmetic S$MPATH 
expression. 

OC The mnemonic operation code of the record being processed is not a $MPXDV 


valid System/3 assembler operation code. 
OP An invalid operator has been encountered within an arithmetic expression. $SMPATH 


RP Invalid placement of a right parenthesis within an arithmetic expression $MPATH 
has occurred. 


SA An error exists in the format of a variable symbol required in the name $MPSTA 
field of a SETA record, or the operand is blank. 


SB An error exists in the format of a variable symbol required in the name $MPSET 
field of a SETB record, or the operand is not 0 or 1. 


—. Figure B-15 (Part 2 of 3). Error Codes for Macro Processor 
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Error Code Error Description Routine 
SC An error exists in the format of a variable symbol required in the S$MPSTC 
name field of a SETC record, or the operand is not enclosed with 


quotes and delimited by a blank, 


SD A null value for a character self defining term exists within an $MPATH 
arithmetic expression. 


SM Reference to an undefined variable symbol. $MPVST 


SS A set symbol identified on a global record has been identified as S$MPGBL 
another type of set symbol within a previous macro definition. 


The attribute of a set symbol! referenced in the name field of a SETA, $SMPSET, $MPSTA, 
SETB, or SETC record does not match its assigned attribute. $MPSTC 
ST When evaluating a character expression, the value of either term of $MPCEX 


substring is negative or the substring start term is 0. 


SY Syntax error in use of substring or character expression exceeds the $MPCEX 
limits of the input record. 


TF The variable symbol table is full. (The user should split his job into $MPGVA, $MPSTC, 
smaller requests.) $MPSTM, $MPVST 
TV A table-definition record is invalid: SMPDEF 


@ The value does not start in position 14 

@ The argument is not left-justified starting in position 1 
@ The argument exceeds the limits defined for the record 
@ The mnemonic operation code (TABDF) is missing 


Figure B-15 (Part 3 of 3). Error Codes for Macro Processor 


Lo 0 tyre TO EFROK., 
EX Out OF EXTENT. 
DE HARDuARE BRROR. 
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The DTF provides information to the data management 
routines about files you use. You must provide one DTF 
for each file you use in a program. Certain fields serve the 
same purpose in all pre-open DTFs. (Pre-open DTFs are 
reformatted to post-open when they are opened by using 
the allocate and open macro instructions.) Figure 21 
describes the fields common to all pre-open DTFs. 


The figures in this appendix describe both the pre-open 
and post-open DTFs for unit record and disk devices. 


Figure DTF Described 
22 7 MFCU pre-open 
23 MFCU post-open 
24 1442 pre-open 
25 1442 post-open 
26 Line printer pre-open (Model 10) 
27 Line printer pre-open (Model 12) 
28 Line printer post-open (Model 10) 
29 Line printer post-open (Model 12) 
30 Printer-keyboard pre-open 
31 Printer-keyboard post-open 
32 Disk pre-open 
33 5444 disk post-open 
34 5445 disk post-open 
35 Tape pre-open 
36 _ Tape post-open 
37 3741 pre-open 
38 3741 post-open 


The labels given to the fields in these figures are the labels 
generated by the offsets macro instructions, $DTOU, 
$DTOD, and $DTOT. Displacements refer to the right- 
most byte of the field. Addresses in the DTFs point to the 
leftmost byte of the referenced area. 
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Displace- Length 
ment in Bytes 


Figure 21. General Pre-Open DTF 


Field 
Description 


Device 
Address 


External 
Indicators 


File 
Attributes 


Record 
Length 


Address of 
Next DTF 


Field Contents 


Address Device 


X'AO’ R1 (5444 removable disk pack one) 

X'A8’ F1 (5444 fixed disk pack one) 

X'BO’ R2 (5444 removable disk pack two) 

X'B8' F2 (5444 fixed disk pack two) 

X‘CO’ D1 (5445 drive one) 

X‘C8’ D2 (5445 drive two) 

X’FO’ MFCU1 (primary hopper) 

X’F8’ MFCU2 (secondary hopper) 

X’EO’ 5203 printer (left carriage) or 1403 printer 

X’E8’ 5203 printer (right carriage) 

X'10’ 5471 printer-keyboard (console) 

X‘50’ 1442 card read/punch 

X‘40’ 3741 Data Station/Programmable Work 
Station 


Opening of a file may be conditioned by a SWITCH 
statement. Any external indicator bit set on is compared 
to the corresponding UPSI bit in the communication 
region, and if that bit is on, the file is opened. 


Essential information about the file organization and the 
method by which it is to be processed is represented by 
these bits. (See Figures 22-38) 


The hexadecimal length of one logical record for the file. 


The address of the next DTF in the forward chain. This 
is used by the open and close routines to find the next DTF. 


Displace- Length 
ment in Bytes Contents 


Device address: | X‘FO’ | MFCU1 
X'F8’ MFCU2 


External indicator 
Attribute byte 1: 
Bits On Use 
Input 
Output | 
0&1 Combined 
4 Print 
Attribute byte 2: 


* Bit On Use 


a 


4 Dual |/O areas (used only for input) 


Record length in hexadecimal 

Address of next pre-open DTF 

Reserved (used by MFCU data management) 

Address of second read 1OB (supplied by macro processor) 
Address of second read !/O area 

Reserved (used by MFCU data management) 

& Pointer to input/output supervisor error recovery procedure 
Address of first read 1|OB (supplied by macro processor) 
Address of first read !/O area 
Address of first punch 1OB (supplied by macro processor) 
Address of hist punch I/O area 


Address of first print I/O area 


Reserved (used by MFCU data management) 


Figure 22. MFCU Pre-Open DTF 
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Displace- 
Label ment 


$RDDEV 


$RDUPS 
$RDAT1 


$RDAT2 


$RDCHA 
$RDCHB 
$RDARR 
$RDXR1 


$RDLRA 
$RDCMP 


$RDOPR 


$RDSTS 


$RDQ 
$RDR 
$RDSTA 
$RDSNS 
$RDWKA 
$RDSVA 
$RDERP 
$RDRIO 
$RDUIO 
$RDPUB 
$RDPTB 
$RDPTL 
$RDPUL 


Figure 23. MFCU Post-Open DTF 


Length 


in Bytes 


™ [= MNNONNNN BN] = = 


Contents 


Device address: X'FO’ MFCU1 
X'F8' MFCU2 

External indicator 

Attribute byte 1: 


Bits On Use 
Input 
Output 
Combined 
Print 


Attribute byte 2: 


Bits On Use 
End of file on last read 
File allocated 
Dual !/O areas 
Device used as system input 
/& read on last input operation 
File opened 


Address of next DTF in backward chain 
Address of next DTF in forward chain 

Address recall register save area (return address) 
Register 1 save area (contents of calling program 
register 1) 

Logical record address 

Completion code: 


Code Meaning 


X‘40’ Normal completion 
X’41' Abnormal condition 
X‘42’ End of file indicator 


Operation byte: 


Bits On Meaning 
0 | Read 
1 Print 
2 Punch 
3 Move (deferred operation) 
4-7 Must be zero 
Stacker select/print: 


Bits Setting Meaning 
Print four lines 
Stacker select command given 
Select stacker 1 
Select stacker 2 
Select stacker 3 
Select stacker 4 


Q-byte (device address) 

R-byte 

1IOS/ERP status information 

Sense area 

Work area 

\OS/ERP permanent save area address 
Disk address of ERP 

Read !OB address 

Punch !OB address 

Punch I/O area address 

Print 1/O area address 

Print record length in hexadecimal 
Punch record length in hexadecimal 


Displace- Length 
ment in Bytes Contents 


Device Address, X‘50’ 
External indicator 
Attribute byte 1: 
Bits On Meaning 
0 Input 
47 Output 
0&1 Combined 
; | Attribute byte 2: 
Bit On , Meaning 
4 Dual I/O area 
Record length 
Address of next DTF in forward chain. 


Reserved (used by 1442 data management) 


Address of second read !OB (supplied by macro processor) 


Address of second read |/O area 


Unused 
| Pointer to error recovery work area (10 bytes) 
@ | Address of first read 10B (supplied by macro processor) 
| | Address of first read 1/O area 
Address of first punch |OB (supplied by macro processor) 


Address of first punch I/O area 


Reserved (used by 1442 data management) 


Figure 24. 1442 Pre-Open DTF 
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Displace- Length 
Label ment in Bytes Contents 


Device address, X‘50’ 


$FDDEV 
$FDUPS 
$FDAT1 


$FDAT2 


$FDCHA 
$—DCHB 
$FDARR 
$FDXR1 


$FDLRA 
$FDCMP 


$FDOPR 


$FDSTS 


$FDQ 
$FDR 
$FDSTA 
$FDSNS 
$FDWKA 
$FDSVA 
SFDERP 
$FDRIO 
$FDUIO 
$FDPUB 
$FDPRV 
$FDPUL 


Figure 25. 1442 Post-Open DTF 
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External indicator 
Attribute byte 1: 


Bits On 


Attribute byte 2: 


Bits On 


Meaning 
Input 
Output 
Combined 


Meaning 

Device allocated 

Dual I/O area 

Device used as system input 
/& read on last input operation 
File is opened 


Address of next DTF in backward chain 

Address of next DTF in forward chain 

ARR save area (return address of calling program) 
Register 1 save area (contents of calling program 


register 1) 


Logical record address 


Completion code: 
Code 
X'40' 
X'41' 
X'42' 
Operation byte: 
Bits On 
0 
2 
2&3 


Stacker select: 


Meaning 

Normal completion 
Abnormal completion 
End-of-file indicator 


Meaning 

Read 

Punch 

Punch, no feed 


Bit 5 on, stacker select 
Bit 6 off, 7 on; select stacker 1 
Bit 6 on, 7 off; select stacker 2 


Q-byte (device address) 


R-byte 


10S/ERP status information 


Sense area 
Work area 


1OS/ERP permanent save area address 


Disk address of ERP 


Read 1OB address 


Punch IOB address 


Current processing data area address 
Previous Operation bytes 


Punch record length 


Figure 27. Line Printer Pre-Open DTF (Model 12) 


Device address: X‘E0O’ left carriage, X’E8’ right carriage 
External indicator 

Attribute byte 1; bit 1 on indicates output 

Attribute byte 2; bit 6 on indicates halt on unprintable characters 
Record length 

Address of next pre-open DTF 

Reserved (used by printer data management) 

Address of |OB (supplied by the macro processor) 
Address of output buffer 

Reserved (used by printer data management) 

Overflow line 

Form length 


Reserved (used by printer data management) 


Device address: X‘EO’ left carriage, X‘E8’ right carriage 


External indicator 


Attribute byte 1; bit 1 on indicates output 


Attribute byte 2; bit 6 on indicates halt on unprintable characters 
Record length 

Address of next pre-open DTF 

Register save area 

Logical record address 

Reserved (used by printer data management) 
Reserved (used by printer data management) 
Address of print 1OB | 

Total number of lines per page 

Reserved (used by printer data management) 
Overflow line 

Maximum skip value 

Reserved (used by printer data management) 
Address of print buffer 


Reserved (used by printer data management) 
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Displace- Length 
ment in Bytes 


$PDDEV 


$PDUPS 
$PDAT1 
$PDAT2 


$PDCHA 
$PDCHB 
$PDARR 
$PDXR1 


$PDLRA 
$PDCMP 


Contents 


X‘EO’ left carriage 
X‘E8’ right carriage 


Device address: 


External indicator 
Attribute byte 1; bit 1 on indicates output 
Attribute byte 2: 


Bits On Meaning 
Device allocated 
Dual |/O areas 
Halt on unprintable characters 
File opened 


Address of next opened DTF in backward chain 
Address of next DTF in forward chain 

Address recall register save area (return address) 
Register 1 save area (contents of calling program 
register 1) 

Logical record address 

Completion code: 


Code 
X‘40’ 
Xx‘41' 
X'48’ 


Meaning 

Normal completion 
Abnormal completion 
Overflow 


$PDOPR 
$PDSKB 
¢PDSPB 
$PDSKA 
$PDSPA 
$PDQ 
$PDR 
$PDSTA 


—_— -= = oh at =o oe —= 


$PDSVA 
$PDXLC 
$PDSNS 
$PDERP 
$PDIOB 

S$PDPRA 
$PDLRL 
$PDOFL 
$PDDCT 


=—-=[2 = NNN ND — NY 


Figure 28. Line Printer Post-Open DTF (Model 10) 


Operation code; X‘40’ indicates print 
Skip-before value (line number) 
Space-before value (number of lines) 
Skip-after value (line number) 
Space-after value (number of lines) 
Q-byte (device address) 

R-byte 

1OS/ERP status information: 


Bits On Meaning 
Wait 
Overflow 
Halt for unprintable characters 
Unprintable character detected 
Abnormal condition 


1OS/ERP permanent save area 
Work area 

Sense area 

Disk address of ERP 

Address of buffer-associated |OB 
Address of current !/O area 
Logical record length 

Overflow line 

Position counter 


$PDDEV 


$PDUPS 
$PDAT1 
$PDAT2 


$PDCHA 
$PDCHB 
$PDARR 
$PDXR1 

$PDLRA 
$PDCMP 


$PDOPR 
$PDSKB 
$PDSPB 
$PDSKA 
$PDSPA 
$PDO 

$PDR 

$PDIOB 
$PDLP 

$PDPCT 
$PDOFL 
$P DMSK 
$PDPGS 
$PDPRA 
$PDRCL 
$PDRES 


Displace- 
ment 


Length 
in Bytes 


-— a AQ = = = = A) = = | = = = = 


Contents 


Device address: X‘EO’ left carriage 
X‘E8’ right carriage 

External indicator 

Attribute byte 1; bit 1 on indicates output 

Attribute byte 2: 


Bits On Meaning 
Device allocated 
Dual 1/O areas 
Halt on unprintable characters 
File opened 


Address of next opened DTF in backward chain 

Address of next DTF in forward chain 

Address recall register save area (return address) 

Register 1 save area (contents of calling program register 1) 
Logical record address 

Completion code: 


Code Meaning 

X‘'40' Normal completion 
X‘41' Abnormal completion 
X‘48' Overflow 


Operation code; X‘40’ indicates print 
Skip-before value (line number) 
Space-before value (number of lines) 
Skip-after value (line number) 
Space-after value (number of lines) 
Q-byte (device address) . 
R-byte 

Address of current 1OB 

Lines per page 

Position counter 

Overflow line counter 

Maximum skip value 

Page size save area 

Address of current !/O area 

Record length 

Reserved 


Figure 29. Line Printer Post-Open DTF (Model 12) 
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Displace- Length 
ment in Bytes 


Figure 30. Printer-Keyboard Pre-Open DTF 


Contents 


Device address; X‘10’ 
External indicator 


Attribute byte 1: 


Bits On Meaning 
0 Input 
Output 
0&1 Both input and output 


Attribute byte 2: 


Bit On Meaning 
6 Halt on unprintable characters 


Record length 

Address of next pre-open DTF 
Return address register save area 
Register 1 save area 

Reserved 

Completion code 

Operation code 

Logical record length 

Length of operator reply 

Space before/space after byte 


Logical record address 


Displace- 
Label ment 


Length 


in Bytes Contents 


$CDDEV Device address; X‘10' 


$CDUPS 
$CDAT1 


$CDAT2 


$CDCHA 
$CDCHB 
$CDARR 
$CDXR1 


$CDLRA 
—$CDCMP 


$CDOPR 


$CDCT1 
$CDCT2 
$CDSPC 


$CDIO2 


Figure 31. Printer-Keyboard Post-Open DTF 


External indicator 
Attribute byte 1: 


Bits On Meaning 
0 Input 
1 Output . 
0&1 Both input and output 


Attribute byte 2: 


Bits On Meaning 
1 Device allocated 
6 Halt on unprintable characters 
7 File opened 


Address of next DTF in backward chain 
Address of next DTF in forward chain 

Address recall register save area (return address) 
Register 1 save area (contents of calling program 
register 1) 

Logical record address 

Completion code: 


Code — Meaning 

X‘00’ Operation has been initiated 
but no wait for completion 
has been executed, or CHEK-Y 


is specified and the operation 
is not completed 

X‘40' Normal completion 

X'41' Abnormal completion 

X'42' __End-of-file indicator 


Operation byte: 


Bits On Meaning 
Input 
Output 
Write/read (WTOR) 
Issue input request only when 
the request key is depressed 
Operator must key the exact 
number of characters 


Count of.bytes in the first area 
Count of bytes in the second area 
Space command: 


Bits Contents 

0-3 Number of lines to space 
before print ° 

4-7 Number of lines to space 
after print 


Address of input buffer 
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Displace- | : 
ment Contents @ 


Device address (any valid disk device) 

External indicators (UPS!) 

File attributes 

Record length 

Address of next DTF 

Reserved for post-open DTF 

Logical record address (move mode) 

Reserved for post-open DTF 

Input/output area address (address of the area 

for |OBs and |/O buffers) 

Reserved for post-open DTF 

Block length (length of a physical block of 

records; used to determine the size of the 

data |/O buffers) . 
Reserved for post-open DTF 

Address of MVF extent tabel (direct multivolume) 
Number of MVF table extents (direct multivolume) 
Reserved for post-open DTF 

Filename (used to identify a disk file) 

Reserved for post-open DTF 

Reserved for post-open DTF (as required) 
Address of requested key (indexed random) or 
address of record address area (direct) 

Address of current key (indexed sequential add) 
Address of high key (processing within limits) 
Reserved for post-open DTF (as required) 

Key length (indexed) 

Reserved for post-open DTF (as required) 

Key displacement in record (indexed) 

Address of master track index (indexed random) 
Address of last key (indexed sequential add) 
Address of low key (processing within limits) 
Number of bytes in master track index (indexed 
random) 

Reserved for post-open DTF (as required) 


NNN ANNO N — = 


NON 


4 
2 
2 
1 
8 
5 
5 
2 


1. DTF fields common to all pre-open DTFs (see Figure 21). 

2. Work buffer address not required for the Allocate Initiator or Open, but will be kept for post-open DTF. 
3. DTF fields common to all pre-open disk DTFs. 

4. Use of these fields varies with the type of access method used. 


Figure 32. Disk Pre-Open DTF 


Field 
Name Length Contents 


$DFDEV 0 1 Device address 
| X‘A0’=R1 
X‘A8' = F1 
X‘BO’ = R2 
X‘B8’ = F2 
$DFUPS 1 1 External indicator 


$DFATR 3 2 File attributes 


Byte 7: 


Bit On Meaning 
Indexed 
Consecutive 
Direct 
Multivolume 
Input 
Output 
Update 

Add 


NOOO PWN — O 


Meaning 
Binary 
Ordered load 
Random 
Limits 
Double buffers/shared 
|/O-move mode 
@ Closed by end of volume 


End of volume/limits 


Opened 
$DFCHA 5 2 DTF chain pointer A (backward) 
$DFCHB 7 2 DTF chain pointer B (forward) 
$DFARR 9 2 ARR save area (return address) 
$DF XRS 11 2 XR1 save area (contents of object program XR1) 
$DFWKB 13 2 Address of logical record (chared |/O-address of 
logical input record) 
$DFCMP 14 1 Completion code 
Code Meaning 
X‘40' Normal completion 
X'41' Controlled cancel taken on 
z . permanent 1!/O error 
X'42' End of file (input) 
X'44’ No record found (out of extent 
; for direct files) 
X‘48’ Overflow (printer) 
X‘50' Key field does not match 
key in update record 
X‘60' Duplicate load or add attempted 
X'62’ Out of sequence (load or add 
attempted) 
X‘70' End of extent (output) 
Completion codes other than X‘40’ are returned 
before the data management function is actually 
completed. 
6 Figure 33 (Part 1 of 3). 5444 Disk Post-Open DTF 
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End of Basic DTF 


End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


$$CSOP 
$$CSIP 
$$CSUP 


$$DAIB 
$$DAID 
$$DAIM 
$$DAIT 
$$DAUB 
$$DAUD 
$$DAUM 
$$DAUT 


$$l1OUT 
$SISIP 
$$ISUP 


Field 


Name Length Contents 
fi i a gh me MB as ee a a ee he a eg en chee ek la a fe a tt Tee ee lan a Ba a 2 
$DFOPC 15 Operation byte: 


Bit on Meaning 
0 Get 
1 Put/add or put/load 
2 Put/update | 
3-7 Must be zero 


Address of current !/O |OB 
Address of current process 1OB (dual I/O only; 
shared |/O-address of logical output record) 


$DFIOB 
$DFPRB 


NI NO 


$DFBKL 2 Block length (length of data buffer) 
$DFRCL 2 Logical record length 

$DFPTR 2 Data block index (address of next record) 
$DFXTA 2 Data start extent 

$DFEMVF (2) Address of direct MVF extent table 
$DFXTB 2 Data end extent (disk address) 

$DFNUM (2) Number of extents (direct MVF) 

S$DFSWA 1 Scheduler work area format-1 label sequence 


number 


S$DFWAA 1 Work area A 

$DFWAB 1 Work area B 

$DFWAC 1 Work area C 

$DFWAD 1 Work area D 

$DFRMA 2 Work area, length of first part of overlap record 
$DFRMB 2 Work area, length of second part of overlap 


record . 
Indicator bits 
Disk address of current record (CSDD) 


$DFIND 
$DFNXR 


bt = 


Disk address of logical end of file (CSD) 
or for direct files, maximum number (in 
binary) of records in the file 


$DFEOF 3 


Disk address of logical end of index (CSD) 
Pointer within index (pointer to next buffer entry) 
Address of key in core (last Get or Put) 


$DFNXK (3) 
$DFKPR 2 
$DFKAD 2 


$DFCUR (2) Address of current key (ISAD, ISUA) 

$DFHI (2) Address of high key (limit) 

$DFKXA 2 Start extent of index (disk address of first track) 
$DFKBF 2 Address of index |OB 

$DFKL 2 Key length 

$DFKXB 2 End extent of index 

$DFKD 2 Displacement of key in record 


cigure 33 (Part 2 of 3). 5444 Disk Post-Open DTF 


68 


End of DTF for: 


End of DTF for: 
End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


$SISIL 

$SSISUL 
$$10AD 
$$IRIP 

$$IRUP 
$$IRAD 
$$IRUA 


$$1SAD 


$$ISUA 


$SISIM 
$$SISUM 
$$CSIM 
$$CSOM 
$$CSUM 
$$10UM 
$$ISAM 
$$iSBM 
$$IRIM 
$$1RUM 
$$IRAM 
$$1OAM 
$$IRBM 


2 
$DFKEY Address of volume information table 
2 


Field 

Name Length Contents 
$DFLST 

$DFMIX 

$DFLOW 


$DFBYT 2 Number of bytes in master index 
$DFKXP | Logical start of index overflow (CSD) 
2 
72 


Address of last key (ISAD, ISUA) 
Address of master track index 
Address of low key (limit) 


Save next index pointer (ISAD, ISUA) 
Save last address (CS) (ISUA) 
Save last index pointer (ISUA) | 


Logical sequence number of current SWA F1 
Actual sequence number of current volumes 
First byte of saved SWA F1 

Last byte of saved SWA F1 . 

ARR save area (return address for Disk Data 
Management when going to End of Volume) 

XR1 save area (contents of Disk Data 
Management XR1 when going to End of Volume) 


Oo) 
oQO_-| = = 


$DFAR1 


$DFXR1 141 


Address of indexed MVF extent table 
Number of track index entries in the volume 
information table - 

Number of on-line indexed MVF volumes 


$DFTAB 
$DFENT 1 
S$DFVOL 1 


Figure 33 (Part 3 of 3). 5444 Disk Post-Open DTF 
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Length of DTF for Field 
Various Modules Name 


DeerOEG | 


$DFUPS 
$DFATR 


$DFCHA 
$DFCHB 
$DFARR 
$DFXRS 
$DFWKB 
$DFCMP 


Figure 34 (Part 1 of 3). 5445 Disk Post-Open DTF 


tor_| om | Length Contents 
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Device address 
X’‘CO’ D1 
X’C8’ D2 

External indicator 

File attributes 


Byte 7: 


Bit On 


Meaning 
Indexed 
Consecutive 
Direct 
Multivolume 
Input 
Output 
Update 

Add 


NO OP WKH -— © 


Meaning 


0 Binary 

1 Ordered load 

2 Random 

3 Limits 

4 Double buffers/shared |/O- 
move mode 

5 Closed by end of volume 

6 End of volume/limits 


Opened 


DTF backward chain pointer 
DTF forward chain pointer 
ARR save area (return address) 
XR1 save area 

Address of logical record 
Completion code 


Code Meaning 

X‘40' Normal completion 

X‘41' Controlled cancel taken on 
permanent I/O error 

X‘'42' End of file (input) 

X'44' No record found (out of extent 
for direct files) 

X‘48' Overflow (printer) 

X‘50° Key field does not match key 
in update record 

X‘60' Duplicate load or add attempted 

X‘62’ Out of sequence (load or add 
attempted) 

X‘70’ End of extent (output) 


Completion codes other than X‘40’ are returned 
before the data management function Is actually 
completed. 


Length of DTF for 
Various Modules 


End of Basic DTF (16 bytes) 


End of DTF for: $$CFOP 
(48 bytes) 


$$CFIP 
End of DTF for: SSC FUP 
(57 bytes) 


$$DFIB 
$$DFID 
$$DFIM 
$$DFIT 
$$DFUB 
$$DFUD 
3 $$DFUM 
End of DTF for: $$DFUT 
(61 bytes) 


$$IFUT 

S$SIHIP 
End of DTF for: $$IHUP 

(72 bytes) 


Field 
Pci Length Contents 


ESS aS ASE Sy (SS PES oT 
Teaco FOPC Operation byte: 


Bit On Meaning 


Get 

Put/add or put/load 

Put/update 

Must be zero 
Address of current 1OB 


Address of current process |OB 
(dual 1/O only) 


$DFIOB 
$DFPRB 


NON 


$DFBKL 2 Block length (length of data buffer) 
$DFRCL 2 Logical record length | 

$DFPTR 2 Data block index (address of next record) 
$DFXTA 2 Data start extent 

$DFMVF (2) Address of direct MVF extent table 
$DFXTB 2 Data end extent (disk address) 

$DFNUM (2) Number of extents (direct MVF) 
$DFSWA 1 Scheduler work area format-1 label 


sequence number 


$DFWAA 1 Work area A 
$DFWAB 1 Work area B 
$DFWAC 1 Work area C 
$DFWAD 1 Work area D 
$DXRMA 3 Work area (length of first part of 


overlap record) 

Work area (length of second part of 
overlap record) 

Indicator bits 

Disk address of current record 
Number of tracks in split cylinder file 


$DXRMB 


1e¥) 


$DXIND 
$DXNXR 
$DXSPC 


o— 


Save area for disk address from 1OB 
Save area for buffer pointer from [OB 
Disk address of logical end of file or for 
direct files, maximum number (in binary) 
of records in the file 


$DXIOA 
$DXDAT 
$DXEOF 


$DXNXK 
$DXKPR 


Disk address of logical end of index 
Pointer within index (to next buffer 
entry) 

Address of key in core (last get or put) 


$DKKAD 


$DXCUR 
$DXHI 
$DXKXA 


Address of current key 
Address of high key (limit) 

Start extent of index (disk address of 
first track) 


$DXKBF Address of index 1O0B 
$DXKL Key length 
$DXKXB End extent of index 


$DXKD Displacement of key in record 


Figure 34 (Part 2 of 3). 5445 Disk Post-Open DTF 
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72 


Length of DTF for 


Various Modules 


End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


End of DTF for: 


$$IHUL 
SSIHIL 
(74 bytes) 
$SSIGIP 
$$1GUP 
(76 bytes) 
$$1FAD 
$$IGAD 
$$IGUA 
(78 bytes) 
$$I1HAD 
(80 bytes) 


$$IHUA 
(85 bytes) 


SSIHIM 
$$1HUM 
$$CFIM 
$$CFOM 
$$CFUM 
(155 bytes) 
$SIFUM 
$$SIHAM 
$$1HBM 
(157 bytes) 
$SIGIM 
$$1GUM 
$$1GAM 
$$IFAM 
$$1GBM 
(161 bytes) 


Field 
Name 


Length Contents 
$DXLST 73 2 Address of last key 
$DXMIX 73 (2) Address of master track index 
$DXLOW 73 (2) Address of low key (limit) 


Reserved 


— 
82 
34 
85 


Logical start of index overflow 


Save next index pointer 


Save last address 
Save last index pointer 


$DXSNP 
$DXSLA 
$DXSLP 


$DXSEQ 


2 
(4) 
2 
3 
2 
1 


Logical sequence number of current 
SWA F1 

Actual sequence number of current 
volumes 

First byte of saved SWA F1 

Last byte of saved SWA F1 

ARR save area (return address for 
disk data management when going to 
end of volume) 

XR1 save area (contents of disk data 
management SR1 when going to end 
of volume) 


$DXNXT 86 


$DXF1S 
$DXF1 
$DXAR1 


$DXXR1 


$DXKEY 156 


Address of volume information table 


$DXTAB ° 158 Address of index MVF extent table 


$DXENT 159 Number of track index entries in 
volume information table 
Number of online indexed MVF 


volumes 


Oo 
~_ = NO N NO NO = _ 


$DXVOL 160 


Figure 34 (Part 3 of 3). 5445 Disk Post-Open DTF 


Device address 

External indicator (see note) 
Attributes 

Attributes 

Record length 

Address of next DTF 

Not used 

Logical record area 

Not used 

Address of 1/O area 

Length of I/O area (see note) 
Block length 

Not used 

Attributes 

Not used 

File name 

Buffer offset (ASCII only) 


Note: These positions are not used in the Pre-Open Basic DTF 


Figure 35. Tape Pre-Open DTF 


1 
1 
1 
1 
2 
2 
4 
2 
2 
2 
2 
2 
6 
1 
2 
8 
1 


Pay 
_ 


S$TDDEV 


$T DERP 
$TDATR 


$TDCHA 
$TDCHB 
$TDARR 
$TDXRS 
$TDWKR 
$TDCMP 


$TDOPC 


— $TDIOB 


$TDPRB 
$TDBKL 
$TDRLC 
$TDPTR 
$TDCRL 


~$TDAT2 


Figure 36 (Part 1 of 2). 


Tape Post-Open DTF 


Device address (X‘60’) 
External indicator (See Note) 
Attribute byte 0 


Meaning 

Consecutive (Always on) 
Multivolume file 

Input 

Output 

Basic access method 


Attribute byte 1 


“ 
~ 


Meaning 
mead Rewind 
Leave 

Standard labeled file 
Locate mode 

Multiple buffering 
Deferred open 

Force EOV call to close 
Opened 


NOoOhWN-O 


DTF backward chain pointer 

DTF forward chain pointer 

ARR save area (return address) 

XR1 save area (object program’s XR1) 
Address of the logical record 
Completion code: 


Code Meaning 

X‘40' Normal! completion 

X'41' Controlled cancel taken on 
permanent !/O error 

X'42' End-of-file (input) 

X‘70’ | End-of-volume (output) 

X'90' Incorrect length on input 
operation 


Operation byte: 


Code 
X‘40' 
X‘80’ 


Meaning 
Put 
Get 


Address of current |/O |OB 

Address of current process 1OB (See Note) 
Block length (Length of data buffer) 
Maximum record length (See Note) 

Block index (See Note) 

Current record length 

Attribute byte 2 


& 
~ 


NOOR WN - OO 


Meaning 

Fixed 

Variable 

Unblocked 

Blocked 

Not used 

ASCII Format D 

ASCII file being processed 
Closed (Multivolume files only) 


Define the File Control Blocks 


73 


1D 1 | 


$TDHTC Not used 
$TDNUM SWA Format 1 number 
$TDWAA Work area A (Block length counter 
for variable length records) (See Note) 
$T DWAB Work area B (Buffer offset for 
: ASCII) (See Note) 
$TDWAC Work area C (Block count); used by 
$TDWAD Tape Close to write or compare 
block count. Basic users must up- 
date this count. (See Note) 
Work area D (Block count save area) 
(See Note) 


$TDIND Indicator bits 


Bit Meaning 

0 CPR IOB has not been 
waited on . 
Truncated block 
Empty variable length 
block 
EOV call to close 
$$CDVE encountered 
error reading trailer label 


Note: These positions are not used in the Post-Open Basic DTF 


Figure 36 (Part 2 of 2). Tape Post-Open DTF 


Displace- 
ment Bytes Contents 


0 1 1 Device address (X‘40’) 
1 1 1 External indicators (UPS!) 
3 2 1 File attributes 
5 2 1 Record length 
7 2 1 Address of next DTF 
11 4 Reserved for post-open DTF 
13 2 2 Logical record address (move mode) 
15 2 Reserved for post-open DTF 
17 2 input/output area address (address of the area 
for |OBs and !/O buffers) 
19 2 Reserved for post-open DTF 


21 2 Block length (length of a physical block of 
records; used to determine the size of the 
data |/O buffers) 


25 4 Reserved for post-open DTF 
27 2 Address of MVF extent tabel (direct multivolume) 
" 29 2 Number of MVF table extents (direct multivolume) — 
30 1 Reserved for post-open DTF 
38 8 Filename (used to identify a file) 


i 1. DTF fields common to all pre-open DTFs (see Figure 21). 
2. Work buffer address not required for the Allocate Initiator or Open, but will be kept for post-open DTF. 


Figure 37. 3741 Pre-Open DTF 


Define the File Control Blocks 75 


76 


Field 
Name Length Contents 
oe 


$DFDEV 


$DFUPS 
$DFATR 


$DFCHA 
$DFCHB 
$DFARR 
$DFXRS 
$DFWKB 


$DFCMP 


Figure 38 (Part 1 of 2). 


a a a ae ee EE eg ee eee 
Device address (X‘40’) 


External indicator 
File attributes 


Byte 7: 


Bit On Meaning 

Unused 
Consecutive 
Unused 
Unused 
Input 
Output 
Unused 
Unused 


Meaning 


Unused 


Double buffers 


Unused 


Opened 


DTF chain pointer A (backward) 

DTF chain pointer B (forward) 

ARR save area (return address) 

XR1 save area (contents of object program XR1) 
Address of logical record (shared !/O-address of 
logical input record) 

Completion code 


Code Meaning 

X'40' Normal completion 

X'41' Controlled cancel taken on 
permanent 1/O error 

X‘42' End of file (input) 


Completion codes other than X‘40' are returned 
before the data management function is actually 
completed. 


3741 Post-Open DTF 


End of Basic DTF 


Field 
Name 


$DFOPC 


$DFIOB 
$DFPRB 


$DFBKL 
$DFRCL 
$DFPTR 
$DFXTA 
$DFMVF 
$DFXTB 
$DFNUM 
S$DFSWA 


$DFWAA 
$DFWAB 
$DFWAC 
$DFWAD 
$DFRMA 
$DFRMB 


Figure 38 (Part 2 of 2). 3741 Post-Open DTF 


_ 
— 


BA VMWNNNNNNA 


— 


RON — = = = 


Meaning 

Get 

Put/add or put/load 
Put 


Must be zero 


Address of current I/O |OB 

Address of current process 1OB (dual I/O only; 
shared |/O-address of logical output record) 
Block length (length of data buffer) 

Logical record length 


Unused 


_ Data block index (address of next record) 


Scheduler work area format-1 label sequence 


number 


Unused 


Define the File Control Blocks 


77 


78 


You build the disk 1OB by issuing the $1|OBD macro 
instruction. If you use $RDD, $WRTD, or $WAIT in your 
program, you must use the $10ED macro instruction to 
assign the offset in the |OB. The format of the |OB and 
the labels assigned to the fields are shown in Figure 39. 
IOBs for the IBM 5444 Disk Storage Drive are 22 bytes 
long; for the IBM 5445 Disk Storage Drive, the IOBs are 
26 bytes long. 


Appendix C. Disk Input/Output Block 


Disk Input/Output Block 79 


Displace- 
Label ment 


Length 
in Bytes 


$DICHN 


$DICMP 


$DIQB 


$DIRB 


$DICB 
(5444 
only) 


$DIFL2 
(5445 
only) 


$DISB 
(5444 
only) 


$DINB 
(5444 
only) 


$DIDAD 
(5445 
only) 


$DIDAT 


Figure 39 (Part 1 of 2). Disk 1|OB Format 


80 


Contents 


Address of the next IOB in the chain. !OBs are chained only when the file requires 
more than one |OB. This area is always present, even when chaining is not used. 
When the operation specified by this 1|OB is complete, this area contains the disk 
address last used (cylinder/sector for the 5444; head/record for the 5445). 


A 1-byte completion code indicating the status of the operation just performed. 
You should check this byte before assuming that the data transfer has occurred.: 
Before the wait routine is called, each bit in this byte has the following meaning: 


Bit On 


ORONO 


~ oO 


Meaning 

Seek has been started on the operation requested by the IOB. 
The operation requested is complete. 

Data transfer is pending on this operation. 

Data transfer has been started on this operation. 

A wait will occur for this lOB. 

If bit 7 is also an, there is an error on an associated IOB; if 
bit 7 is off, a scan equal has been found. 

The scan is not satisfied. 


A permanent error has occurred on this |OB or an associated IOB. 


After the wait routine has finished, the code in this byte has the following 


meaning: 


Code 
X’40’ 
X‘41’ 
X’42’ 
X‘44’ 
X'45' 


The Q-byte of the start !/O (SIO) command. You set this byte through the $10BD 
macro instruction. 


Meaning 

Successful completion. 

Permanent !/O error. 

Scan not satisfied. 

Scan equal found. 

Permanent error on an associated !OB. 


The R-byte of the start |/O command. It further defines the operation requested. 
Figure 40 shows the possible R-byte settings for the SIO command. 


The hexadecimal value of the cylinder address where the operation is to begin. 
You set this byte through your $1OBD macro instruction. 


Flag byte for use with the 5445. The meanings of the bits are: 


Bit On 
0 
1 


Meaning 

End of cylinder has been reached. (Used by IOS only.) 

End of cylinder has been reached. You may test this bit when 
control is returned to your program. 

Not used. 

Seek not used on this operation. 

Reserved; must be 0. 


The hexadecimal value of the beginning sector address of the operation. You 
set this byte through the $10BD macro instruction. 


The number of sectors minus one, in hexadecimal, involved in the data transfer. 
You set this byte through the $1OBD macro instruction. 


Address of the leftmost byte of the 5445 disk address. 


Address of the leftmost byte of your data area. You provide this address 
through the $10BD macro instruction. 


« 


Displace- Length 
Label ment in Bytes Contents 
11 


$DISNS 


The area used by the input/output supervisor to contain device status sense 
information. The contents of this area is described in Figure 41. 


$DIERR 12 The area used by disk 1OS to count the number of retries required to 
complete the !/O request. 


$DIFLG Indicates special handling required for !/O operations through the various 
- bit settings. You set bits O and 4 through the $1O0BD macro instruction. If no 
special handling is required, the byte must be set to X‘00’. The bit settings are: 


Bit On Meaning 
0 No recovery is to be attempted if a data check, missing address 

mark, no record found, or track condition check error condition 
occurs. 
No verification is to be done on write operations. 
No error logging is to be done if any disk 1/O error should 
occur. Control is to be returned to the calling routine. 
Disk 1OS should not use the C and S bytes in the IOB, but 
should pick up the F, C, and S bytes at the end of the 1|OB 
for use in this operation. This bit should be used only by 
the system control program. 
The calling routine is not using disk data management; there- 
fore, this 1OB is not associated with a DTF. 
There is no load 1/O of the disk file data register (DFDR). 
Error logging is in progress. 
A data transfer operation involving an alternate track is in 
progress. 


$DIARR The save area for the address recall register. 


$DIXR2 The save area for register 2. 


$DIDCH The disk data management chain pointer. It contains the address of the 
second of the two IOBs used for double buffering. 


$DIDTF The address of the DTF associated with this |OB. 
$DICC The hexadecimal value of the cylinder address where the operation is to 
(5445 begin. You set this byte through the $10BD macro instruction. 
only) 
$DIHH The hexadecimal value of the head address where the Operation is to begin. 
(5445 You set this byte through the $10BD macro instruction. 
only) : 
$DIR The hexadecimal value of the record address where the operation is to begin. 
(5445 You set this byte through your $1OBD macro instruction. 
only) 
$DIN The number of records minus one, in hexadecimal, involved in the data 
. (5445 transfer. You set this byte through the $10BD macro instruction. 


only) 


Figure 39 (Part 2 of 2). Disk 1OB Format 


Disk Input/Output Block 81 


82 


1/O 
Operation 


5444 Settings _ 


SiO R-Byte 
Settings (Hex) 


02 


Interpretation 


Data 
Identifier 

. Diagnostic 
Verify 


Equal 
Low or equal 
High or equal 


5445 Settings 


Figure 40. R-Byte Settings 


00 
| 03 


Seek 
Recalibrate 


Key-data 
Verify key-data 


Key-data equal 
Key-data low or equal 
Key-data high or equal 


1/O no-op (single only) 
Intervention required 
Missing address mark 
Equipment check 
Data check 

No record found 
Track condition check 
Seek check 


NOOR WN = O 


Scan equal 

Access arm at cylinder O 
End of cylinder 

Seek busy 

Hundred cylinders 
Device overrun 

Status address A* 

Status address B* 


NO O1R WN — O 


Format error 
Intervention required 
Missing address mark 
Equipment check 
Data check 

No record found 
No-op 

Overrun 


0 
1 
2 
3 
4 
5 
6 
7 


Disk drive error 

Unsafe 

Seek 1 complete 

Seek 2 complete 

Data operation complete 

End of cylinder has been reached 
Scan equal 

Disk drive 1D** 


NOOR WN = © 


Indicates which drive on the 5444 had last data transfer: 
Bits 6-7 00—Drive 1 
. 01—Drive 2 


O—Drive 1 
1—Drive 2 


Figure 41. Device Status Sense Information 


Disk Input/Output Block 83 


84 


Figure 42 is asummary chart containing all valid macro 
processor instructions. The macro instructions are listed 
in alphabetic order. Four items are given for each macro 
instruction: 


e Name 

@ Format of the instruction with all valid operands 
e Function of the macro instruction 

@ Maximum number of statements generated 


For more detailed information on any of the macro 


instructions, see Chapter 2. Macro Instruction Statements. 


Appendix D. Macro Instruction Summary Chart 


Macro Instruction Summary Chart 
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98 


weYyD AseMWNS UO!JONA}sU] CADE “(fp JO L 14ed) Tp aanbiy 


Maximum Number 


of Statements 


Macro Instruction Generated 

$ALOC [Name] $ALOC [DTF-address] Assigns the file indicated by the DTF to 5 7 
your program. 

$S$CCP [Name] $CCP OBYTE-hex,RBY TE-hex Generates the CCP assembler 4 

instruction. 

$CHK [Name] $CHK [CKL-address] Tests for |/O operation completion in the 4 
check list. 

$CKL [Name] $CKL DTF-address[{,SKIP-Y/N] [,REOK-Y/N] [,RTN-Y/N] Generates an entry for the check list to be 6 

[,LAST-Y/N] ° used by the check routine. 
$CLOS [Name] $CLOS [DTF-address] Prepares the device for job termination. 5 


$COMN | | $COMN | | Provides equates used by various other 14 


macro instructions. 


$CTLT [Name] $CTLT {[DTF-address] [,OPC-code] Issues control commands to the tape device. 5 


$DTFD [Name] $DTFD AC-code,RECL-number ,NAME-filename,|O-address, Builds a DTF for a disk file. 43 
BLKL-number[,DISK-5444/5445] [,UP-mask] 
[,BUFNO-1/2] [,MVF-N/Y] [,LIM-N/Y] 


[,.ORD-N/Y] [,BIN-N/Y] [,CHN-address] 
[,RCAD-address] [,ENT-number] [,MVFEN-number ] 
[, KEYL-number] [,KEYD-number] [,KEYA-address] 
[,MVFT-address] [, MST X-address] 


$DTFK NAME-filename,RECL-number, !O-address Builds a DTF for 3741 file. 15 
[,AC-1/O] [,RCAD-address] [,BUFNO-1/2] 
[,CHN-address] [,UP-mask] 


$DTFT NAME-filename,|O-address,AC-IN/OUT,BLKL-number,| | Builds a DTF for a tape file. 23 
RECL-number[,UP-mask] [,CHN-address] 

[,BASIC-Y/N] [MODE-LOCATE/MOVE] 

[,MBUFF-Y/N] [,RCAD-address] [,RECFM-code] 

[,LIOA-number] [,SPAN-Y/N] [,CODE-A/E] 


[,OSET-B/number] [,END-code] 
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Figure 42 (Part 2 of 4). 
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queyd Aseuuwing uo!oNIysUuj O19eW 


68 


"(p30 p Med) Zp eanbig 


HeYyD Asewwins uondnajsu} Ose) 


$TRL 


$TRTB 


$WRTD 


$WAIT 


S$WRTT 


SWTT 


$XCTL 


Macro Instruction 


[Name] 


$TRL 


TO-address,-F ROM-address,_LEN-number, 
TRT-address 


[Name] $TRTB [CODE-E/A] [,HEX-hex] 


[Name] 


$WRTD 


1OB-address ,CS-address, NSECT-number 
[ ,DISK-5444/5445] 


| [Name] | $WAIT | [1OB-label] [,ERR-address] | 


[Name] 


[Name] 


[Name] 


SWRTT 


$WTT 


$XCTL 


[DTF-address] 
{[DTF-address] [,ERR-address] [,EOF-address] 
[,EOT-address] 


NAME-module name[,LOAD-2/address] 
[,PACK-P/S] 


Builds a parameter list to pass infor- 
mation to the system translate routine. 


Generates an EBCDIC to ASCII or an 
ASCII to EBCDIC translate table. 


Writes a record on a disk file via the 
input/output supervisor. 
Waits for completion of a disk input/output 


Operation. 


Writes a record to a tape file via the basic 
tape data management. 


Waits for completion of a basic tape data 
management I/O operation. 


Finds and loads a module at a specified 
address and passes control to it. 


Maximum Numbe 
of Statements 
Generated 


13 


20 


10 


10 


90 


s 


$SARFF 1442 data management module 26 
$$CFxx disk data management modules 35 
$$COAM console data management module 26 
$$CSxx disk data management modules 35 
$$CSxx tape data management modules 41 
$$DAxx disk data management modules 35 
$$DFxx disk data management modules 35 
$SIFxx disk data management modules 35 
$$1Gxx disk data management modules 35 
$$lHxx disk data management modules 35 
$$10Oxx disk data management modules 35 
$$IRxx disk data management modules 35 
$$LPRT printer data management module 26 
$$MFxx MFCU data management modules 26 
$ALOC macro 18 

$¢CCP macro 48 

$CHK macro 21 

¢$¢CKL macro 20 

$CLOS macro 22 

$COMN macro 5 

$CTLT macro 45 

$DTFD macro 30 

$DTFK macro 46 

$DTFT macro 39 

$DTFU macro 22 

$DTOD macro 32 

$¢DTOT macro 41 

$DTOU macro 25 

$EOJ macro 16 

$FIND macro 11 

$FTCH macro 13 

$GETD macro 34 

$GETK macro 47 

$GETT macro 41 

$GPU macro 25 

$1IOBD macro 33 

$1OED macro 34 

$LCP macro 48 

$LOAD macro 11 

SOPEN macro 19 

$PKBU macro 27 

$PRNT macro 29 

$PUTD macro 37 

$PUTK macro 47 

$PUTT macro 43 

$RDD macro 36 

$RDT macro 43 

$SCP macro 48 

$SNAP macro. 16 

$SOURCE file with macro processor 2 
$SVC macro 6 

$TRAN macro 16 

$TRL macro 14 

$TRTB macro 15 

$WAIT macro 38 

$WRTD macro 38 

$WRTT macro 44 

$WTT macro 45 

$XCTL macro 14 
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access methods, disk data management system 
modules 35 

allocate 1/O devices (GSALOC) 8 

allocate space (SALOC) 18 

assembler instruction generation 48 


BSC DTF checked for completion 20 
buffer length, disk 30 
buffers 
disk 30 
dual 
disk 31 
unit record 23 
3741 46 
unit record 23 
3741 46 


card read punch (see 1442) 
CCP assembler instruction generation 
(SCCP) 48 
chaining DTFs 

close routine 22 

open routine 19 
check for |1/O completion (SCHK) 21 
check list format 20 
check list generation ($CKL) 20 
close I/O device file (S6CLOS) 22 
close routine 22 
coding conventions, macro instruction 1 
command CPU instruction generation 
(SCCP) 48 
command, tape control (SCTLT) 45 
comments, macro instruction 3 
common equates ($COMN) 5 
completion check |/O (SCHK) 21 
completion checklist, |/O (SCKL) 20 
configuration record description 8 
considerations, programming 5 
console (see also printer-keyboard, 5471) 
console data managment module 26 
console get/put/write to operation 
(SPKBU) 27 


Index — 
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continuation coding, macro instruction 
control blocks (see DTF control block 
descriptions) 

control command for tape (SCTLT) 45 
control exchange with loaded module 
(SXCTL) 14 

control pass to loaded module ($FTCH) 
CPU command/load/store instruction 
generation 48 


data area pre-open/post-open 
conditions 19 
data management modules 
console 26 
disk 35 
MFCU 26 
printer 26 
tape 41 
1442 26 
data station (see 3741) 
default value definition 3 
define the file (see DTF) 
deleting macro instructions 4 
device allocation (SALOC) 18 
device preparation (SOPEN) 19 
device status sense information 83 
device support 
disk 29 
tape 39 
unit record 22 
3741 46 
device termination (6CLOS) 22 
directory entry find (SFIND) 11 
disk buffers 30 
disk data management module access 
methods 35 
disk DTF control block descriptions 
post-open (5444 and 3340 simulation 
area) 67 
post-open (5445 and 3340 main data 
area) 70 
pre-open 66 | 
disk DTF definition (SDTFD) 30 
disk get record interface (SGETD) 34 
disk |OB 
build (SIOBD) 33 
description/format 79 
disk put record interface (SPUTD) 37 
disk routines 
build DTF (SDTFD) 30 
build |OB (SIOBD) 33 
generate DTF offsets (GSDTOD) 32 
generate IOB offsets (SIOED) 34 
get record (SGETD) 34 
put record (SPUTD) 37 
read (GRDD) 36 
wait (BWAIT) 38 
write (SWRTD) 38 
disk update (GPUTD) 37 
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disk wait (GSWAIT) 38 
disk write (SWRTD) 38 
DTF build 
disk (SDTFD) 30 
tape (SDTFT) 39 
unit record (SDTFU) 22 
3741 (SDTFK) 46 
DTF chaining 
close routine 22 
open routine 19 
DTF checked for completion, 
BSC/MLTA/5471 20 
DTF control block descriptions 
post-open 
line printer (Model 10) 62 
line printer (Model 12) 63 
MFCU 58 
printer-keyboard (console) 65 
tape 73 
1442 60 
3741 76 
5444 disk (and 3340 simulation 
area) 67 
5445 disk (and 3340 main data 
area) 70 
pre-open . 
disk 66 
general 56 


line printer (Models 10 and 12) 61 


MFCU 57 
printer-keyboard (console) 64 
tape 72 
1442 59 
3741 75 
DTF offsets 
disk (SDTOD) 32 
tape (SDTOT) 41 
unit record (SDTOU) 25 
3741 (GDTOD) 32 
DTF pre-open/post-open conditions 
dual buffers 


disk 31 
unit record 23 
3741 46 


dump main storage (SSNAP) 16 


end of job (SEOJ) 16 
equates 
common ($COMN) 5 
disk DTF (SDTOD) 32 
IOB (SIOED) 79 
tape DTF (SDTOT) 41 | 
unit record DTF ($DTOU) 25 
3741 DTF ($DTOD) 32 
error code descriptions, macro 
instruction 53 
exchange control with loaded module 
(SXCTL) 14 
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a 


fetch module and pass control ($FTCH) 13 
file 
allocation (SALOC) 18 
close (6CLOS) 22 
definition 
disk (SDTFD) 30. 
tape (SDTFT) 39 
unit record (SDTFU) 22 
3741 ($DTFK) 46 
open (SOPEN) 19 
find-and-load module (SLOAD) 11 
find directory entry ($FIND) 11 
find parameter list description 12 
format 
check list 20 
format-1 label 10 
|/O completion checklist 20 
volume label 9 | 
VTOC index 10 
format-1 label 
description 8 
format 10 


generation 
checklist (BCKL) 20 
translate parameter list (STRL) 14 
translate routine interface (STRAN) 16 
translate table (STRTB) 15 

get record 
console (printer-keyboard) (SPKBU) 27 
disk (SGETD) 34 
tape ($6GETT) 41 
unit record ($GPU) 25 
3741 (SGETK) 47 


halt descriptions (error) 53 
halt/syslog message printing (SPRNT) 29 
halt/syslog routine 7 
hexadecimal settings 
Q-byte 33 
R-byte 82 


1/0 completion check (SCHK) 21 
|/O completion checklist (SCKL) 20 
|/O completion checklist format 20 
|/O completion, tape (SWTT) 45 
|/O device file (see file) 

index, VTOC 8 

input buffer (see buffers) 

input devices, system 6 


input/output block (see 1OB) 
input/output support macros 17 
instruction generation, assembler 48 
interrupt program (rollout) 8 
1OB 
address specification, printer 23 
description, disk 79 
for disk 33 
for printer 23 
offsets (SIOED) 34 
1OS routines 17 


job end ($EOJ) 16 


labels 
common ($COMN) 5 
disk DTF (SDTOD) 32 
DTF 55 
format-1 8 
IOB ($SIOED) 79 
tape DTF (SDTOT) 41 
unit record DTF (SDTOU) 25 
volume 8 
3741 DTF (SDTOD) 32 
LCP assembler instruction generation 
(SLCP) 48 | 
length, disk buffer 30 
length, macro instruction 86 
line printer DTF control block descriptions 
post-open (Model 10) 62 
post-open (Model 12) 63 
pre-open 61 
load CPU instruction generation ($LCP) 48 
load module (SLOAD) 11 
load module after find (SFIND) 11 
load module and exchange control 
(SXCTL) 14 
load module and pass control (SFTCH) 13 
load parameter list description 13 
log device definition 7 


Index 
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macro instruction 

coding conventions 1 
comments 3 
continuation 3 
definition/description 1 


deletion 4 
length 86 
list 4 


name field description 1 

operand description 1 

Operation code description 1 

summary 85 
macro processor 

overview 1 

register usage 5 

residence 4 

restrictions 5 

sample program 49 

source statements 2 
main storage snap dump ($SNAP) 16 
message/halt 

definition 7 

descriptions (error) 53 

printing (SPRNT) 29 
MFCU DTF ($DTFU) 22 
MFCU DTF control block descriptions 

post-open 58 

pre-open 5/7 
MLTA DTF checked for completion 20 
module load (SLOAD) 11 
module load after find (SFIND) 11 
module load and control exchange 
(SXCTL) 14 
module load control pass (§SFTCH) 13 
modules, system (see data management 
modules) 


name field description, macro 
instruction 1 


OCL statement examples 49 
offsets 

common (SCOMN) 5 

disk DTF (SDTOD) 32 

1IOB (SIOED) 34 

tape DTF ($DTOT) 41 

unit record DTF ($DTOU) 25 

3741 DTF (SDTOD) 32 
open |/O device file (SOPEN) 19 
open routine 19 
operand description, macro instruction 
operation code description, macro 
instruction 1 
operator interface (SPKBU) 27 
operator reply, console 24 
output buffer (see buffers) 
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parameter list descriptions 

find 12 

load 13 

translate 16 
parameter list generation, translate 
(STRL) 14 
pass control to loaded module ($FTCH) 
physical buffers (see buffers) 


post-open DTF control block descriptions 


line printer (Model 10) 62 
line printer (Model 12) 63 
- MFCU_ 58 
printer-keyboard (console) 65 
tape 73 
1442 60 
3741 76 
5444 disk (and 3340 simulation area) 


13 


67 


5445 disk (and 3340 main data area) 70 


post-open DTF/data area conditions 19 


pre-open DTF control block descriptions 

disk 67 

general 56 

line printer 61 

MFCU 57 

printer-keyboard (console) 64 

tape 72 

1442 59 

3741 75 
pre-open DTF/data area conditions 19 
prepare |/O device file (SOPEN) 19 
prepare |/O device file for termination 
(GCLOS) 22 
print buffer (see buffers) 
print message (SPRNT) 29 
printer (see also line printer) 
printer data management module 26 
printer DTF (SDTFU) 22 
printer |OB address specification 22 
printer-keyboard (console) interface 
(SPKBU) 27 
printer-keyboard (see also console, 5471) 
printer-keyboard data management 
module 26 
printer-keyboard DTF control block 
descriptions 

post-open 65 

pre-open 64 
programmable work station (see 3741) 
programming considerations 5 
punch buffer (see buffers) 
put record 

console/printer-keyboard (SPKBU) 27 

disk (SPUTD) 37 

tape (SPUTT) 43 

unit record ($GPU) 25 

3741 (SPUTK) 47 


Q-byte hexadecimal settings 33 


R-byte hexadecimal settings 82 tape data management modules 41 


read buffer (see buffers) tape DTF control block descriptions 
read routines post-open 73 
(see also get record) pre-open 72 
disk (SRDD) 36 tape DTF definition (SDTFT) 39 
tape (SRDT) 43 tape DTF offsets (SDTOT) 41 
VTOC 7 tape get record interface (SGETT) 41 
record tape put record interface (GPUTT) 43 
(see also read routines, write routines) tape routines 
get | control command ($CTLT) 45 
console (SPKBU) 27 DTF build (SDTFT) 39 
disk (SGETD) 34 DTF offsets (SDTOT) 41 
. tape (GGETT) 41 get record ($GETT) 41 
| unit record (SGPU) 25 put record ($PUTT) 43 
3741 (SGETK) 47 read (SRDT) 43 
, put wait (SWTT) 45 
console (§SPKBU) 27 write (SWRTT) 44 
disk (SPUTD) 37 terminate |/O device file (G6CLOS) 22 
tape (SPUTT) 43 translate area format 14 
unit record (GPU) 25 translate parameter list description 16 
3741 (SPUTK) 47 | translate parameter list generation 
record read (see get record, read routines) (STRL) 14 
record update (see put record) translate routine (Model 10) 14 
record, configuration 8 translate routine interface generation 
register usage, macro processor 5 (STRAN) 16 
residence, macro processor 4 translate table generation ($STRTB) 15 


restrictions 
macro processor 5 
program size 18 
rollout routine 8 

rollout routine (interrupt) 8 


unit record 

(see also MFCU, line printer, printer, 

1442, 5471) 

routines 

DTF build (SDTFU) 22 

sample program, macro processor 49 DTF offsets (SDTOU) 25 
SCP assembler instruction generation get/put (SGPU) 25 
(SSCP) 48 print message (SPRNT) 29 
sense information, device status 83 printer-keyboard interface (SPKBU) 27 
snap-dump main storage (6SNAP) 16 updating records (see put record) 


source statements, macro processor 2 
space allocation (SALOC) 18 

status sense information, device 83 
storage dump, main (SSNAP) 16 
store CPU instruction generation 


(SSCP) 48 
: supervisor call (SSVC) 6 volume label 8 
SYSIN (see system input) volume label format 9 
| syslog (see halt/syslog, system log device) VTOC (volume table of contents) 

. system input device 6 format 8 
system input routine 6 index description 8 
system log device 7 read routine 7 
system routines (see data management read routine description 7 

. modules) 


system services macro instructions 6 
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wait routines 
disk (SWAIT) 38 
tape (SWTT) 45 
work station (see 3741) 
write routines 
(see also put record) 
disk (SWRTD) 38 
printer-keyboard (console) (GPKBU) 27 
tape (SWRTT) 44 
3741 (GPUTK) 47 


1403 
(see also line printer, printer, unit 
record) 
DTF definition (GSDTFU) 22 
1442 
(see also unit record) 
data management module 26 
DTF control block descriptions 
post-open 60 
pre-open 59 
DTF definition (SDTFU) 22 
3340 (see disk) 
3741 DTF control block descriptions 
post-open 76 


pre-open 75 | | | | 
3741 get record interface (SGETK) 47 
3741 put record interface (BPUTK) 47 


3741 routines 
DTF definition (SDTFK) 46 
get record ($GETK) 47 
put record (SBPUTK) 47 
5203 
(see also line printer, printer, unit 
record) 
DTF definition (SDTFU) 22 
5424 (see MFCU) 
5444 (see disk) 
5445 (see disk) 
5471 
(see also console, printer-keyboard, unit 
record) 
data management module 26 
DTF ($DTFU) 22 
DTF checked for completion 20 
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